ProtectPay – Capture a Transaction

Transactions initially authorized using an 'Authorize' event must still be ‘Captured’ before a merchant receives his or her funds. Most Processing solutions offer a way to perform both of these actions with a single API method, and ProtectPay is no exception. This method is not used if you originally 'Process' your payment.

Some merchants, however, prefer to authorize and capture separately. These are their reasons:
  • They can control the window during which a void is still possible. Remember, ProPay no longer allows merchants to void transactions once 1) they have been sent to the credit card brand, or 2) we’ve given the merchant the money for them. ProPay funds transactions on a predictable schedule configured for each merchant, but we send transactions to the credit card brands multiple times per day.
  • They can ‘pick an order’ in their warehouse, and make sure product has shipped before finalizing the charge. Shipping delays, or slow delivery due to inventory shortfalls can upset customers when transactions are finalized long before shipping.
How to call this method?

HTTP URL(s)
HTTP Verb PUT
HTTP Header Authorization
Example Request

Example Response

{
"MerchantProfileId": 12345,
"TransactionHistoryId": "123456789",
"Amount": 300,
"CurrencyCode":"USD"
}
{
"Transaction":
{
"AVSCode": "T",
"AuthorizationCode": "A11111",
"CurrencyConversionRate": 1,
"CurrencyConvertedAmount": 300,
"CurrencyConvertedCurrencyCode": "USD",
"ResultCode":
{
"ResultValue": "SUCCESS",
"ResultCode": "00",
"ResultMessage": ""
},
"TransactionHistoryId": "123456789",
"TransactionId": "300",
"TransactionResult": "Success",
"CVVResponseCode": "M",
"GrossAmt": 300,
"NetAmt": 255,
"PerTransFee": 35,
"Rate": 3.25,
"GrossAmtLessNetAmt": 45
},
"RequestResult":
{
"ResultValue": "SUCCESS",
"ResultCode": "00",
"ResultMessage": ""
}
}
Implementation Details
Request Submission

namespace ProtectPayApi_CaptureTransaction
{
using System;
using System.Text;

using RestSharp;

/*
ProPay provides the following code “AS IS.”
ProPay makes no warranties and ProPay disclaims all warranties and conditions, express, implied or statutory,
including without limitation the implied warranties of title, non-infringement, merchantability, and fitness for a particular purpose.
ProPay does not warrant that the code will be uninterrupted or error free,
nor does ProPay make any warranty as to the performance or any results that may be obtained by use of the code.
*/
public class CaptureTransactionProgram
{
public static void Main(string[] args)
{
var CaptureTransactionResponse = CaptureTransaction();
}

private static CreateTransactionResult CaptureTransaction()
{
var baseUrl = "https://xmltestapi.propay.com/ProtectPay";
var request = BuildCaptureTransactionRequest();
var restRequest = CreateRestRequest("/CapturedTransactions/", RestSharp.Method.PUT);
restRequest.AddBody(request);
return Execute<CreateTransactionResult>(restRequest, baseUrl);
}

private static CaptureTransactionRequest BuildCaptureTransactionRequest()
{
return new CaptureTransactionRequest
{
MerchantProfileId = 123456,
TransactionHistoryId = 6091209,
Amount = 1000,
CurrencyCode = "USD",
};
}

private static RestRequest CreateRestRequest(string resource, Method method)
{
var restRequest = new RestRequest { Resource = resource, Method = method, RequestFormat = DataFormat.Json, };
var credentials = GetCredentials();
restRequest.AddHeader("accept", "application/json");
restRequest.AddHeader("Authorization", credentials);
return restRequest;
}

private static string GetCredentials()
{
var billerAccountId = "5114248593164903"; // biller account id
var authToken = "9d506d3e-b5f7-4474-adb1-76423e113c85"; // authentication token of biller
var encodedCredentials = Convert.ToBase64String(Encoding.Default.GetBytes(billerAccountId + ":" + authToken));
var credentials = string.Format("Basic {0}", encodedCredentials);
return credentials;
}

private static T Execute<T>(IRestRequest request, string baseUrl) where T : class, new()
{
var client = new RestClient(baseUrl);
var response = client.Execute<T>(request);
if (response.ErrorException != null)
{
Console.WriteLine(
"Error: Exception: {0}, Headers: {1}, Content: {2}, Status Code: {3}",
response.ErrorException,
response.Headers,
response.Content,
response.StatusCode);
}
return response.Data;
}

public class CaptureTransactionRequest
{
public long MerchantProfileId { get; set; }
public long TransactionHistoryId { get; set; }
public long Amount { get; set; }
public string CurrencyCode { get; set; }
}

public class CreateTransactionResult
{
public Trans Transaction { get; set; }
}

public class Trans
{
public string AVSCode { get; set; }
public string AuthorizationCode { get; set; }
public decimal CurrencyConversionRate { get; set; }
public long CurrencyConvertedAmount { get; set; }
public resultc ResultCode { get; set; }
public long TransactionHistoryId { get; set; }
public long TransactionId { get; set; }
public string TransactionResult { get; set; }
public string CVVResponseCode { get; set; }
public long GrossAmt { get; set; }
public long NetAmt { get; set; }
public long PerTransFee { get; set; }
public decimal Rate { get; set; }
public long GrossAmtLessNetAmt { get; set; }
public result RequestResult { get; set; }
}

public class resultc
{
public string ResultValue { get; set; }
public string ResultCode { get; set; }
public string ResultMessage { get; set; }
}

public class result
{
public string ResultValue { get; set; }
public string ResultCode { get; set; }
public string ResultMessage { get; set; }
}
}

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values

Request Element

Type

Max

Required

Notes

Id.AuthenticationToken

String

100 Characters

Authorization

Valid value is a GUID. Value supplied by ProPay. Used to access the API

Id.BillerAccountId

String

16 Characters

Authorization

Value supplied by ProPay. Used to identify the correct collection of tokens.

Amount

Int(64)

Int

Required

The value representing the number of pennies in USD, or the number of [currency] without decimals.

Comment1

String

128 Characters

No

Transaction descriptor. Only passed if supported by the gateway.

Comment2

String

128 Characters

No

Transaction descriptor. Only passed if supported by the gateway.

CurrencyCode

String

3 Characters

Required

ISO 4217 standard 3 character currency code.

MerchantProfileId

Integer

Int

Required

Used to specify which processor and merchant account to process the transaction against.

TransactionHistoryId

Integer

Int

Required

ProtectPay’s identifier for the transaction to capture.

**This value is returned by AuthorizePaymentMethodTransaction.

Response Values

Response Element

Type

Notes

RequestResult.ResultValue

String

The ProtectPay API Method Response Value;

SUCCESS indicates the method completed;

FAILURE indicates the method call failed and the reason is indicated in the ResultCode and ResultMessage

RequestResult.ResultCode

String

The ProtectPay API Method Response Code. See ProtectPay Appendix A for possible returned values

RequestResult.ResultMessage

String

The ProtectPay API Method Response Message. See ProtectPay Appendix A for possible returned Messages

AuthorizationCode

String

The auth code supplied by the issuing bank.

*Only returned on a successful transaction

AVSCode

String

AVS response produced by gateway

*Only returned if AVS information is supplied and AVS is supported by the gateway.

CurrencyConversionRate

Decimal

The rate for currency conversion used for multi-currency transactions

CurrencyConvertedAmount

Long

Gross converted amount of transaction in the number of [currency] without decimals for multi-currency transactions

CurrencyConvertedCurrencyCode

String

The currency the transaction was converted to for multi-currency transactions

CVVResponseCode

String

 

GrossAmt

Long

Gross amount of transaction of pennies in USD, or the number of [currency] without decimals.

GrossAmtLessNetAmt

Long

Total amount of fees charged; *ProPay Gateway Only

NetAmt

Long

Net amount of transaction after fees charged; *ProPay Gateway Only

PerTransFee

Long

Per transaction fee; *ProPay Gateway Only

Rate

Decimal

Percentage fee; *ProPay Gateway Only

Transaction.ResultCode.ResultValue

String

The result value of the transaction request as reported by the ProtectPay. SUCCESS or FAILURE

Transaction.ResultCode.ResultCode

String

The result code of the transaction request as reported by ProtectPay. See ProtectPay Appendix A for possible returned values

Transaction.ResultCode.ResultMessage

String

The result message of the transaction request as reported by ProtectPay. See ProtectPay Appendix A for possible returned values

TransactionHistoryId

String

Unique transaction number assigned by ProtectPay.

TransactionId

String

Transaction number assigned by processor (Gateway)

TransactionResult

String

Transaction result as reported by processor (Gateway)

 

How to call this method?

Example Request

Example Response

Implementation Details
Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values
Response Values
How to call this method?

{SOAP Action}     CaptureTransaction
{URL}                   https://xmltestapi.propay.com/protectpay/sps.svc
Example Request

Example Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:con="http://propay.com/SPS/contracts" xmlns:typ="http://propay.com/SPS/types">
<soapenv:Header/>
<soapenv:Body>
<con:CaptureTransaction>
<con:id>
<typ:AuthenticationToken>MyAuthToken</typ:AuthenticationToken>
<typ:BillerAccountId>MyBillerId</typ:BillerAccountId>
</con:id>
<con:request>
<typ:Amount>100</typ:Amount>
<typ:Comment1>Comment</typ:Comment1>
<typ:Comment2>Commenta</typ:Comment2>
<typ:CurrencyCode>USD</typ:CurrencyCode>
<typ:MerchantProfileId>123456</typ:MerchantProfileId>
<typ:OriginalTransactionId>1245</typ:OriginalTransactionId>
<typ:PaymentMethodId>4945f470-1379-4cab-8e2a-ebf3fc424f75</typ:PaymentMethodId>
<typ:TransactionHistoryId>1155234</typ:TransactionHistoryId>
</con:request>
</con:CaptureTransaction>
</soapenv:Body>
</soapenv:Envelope>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<CaptureTransactionResponse xmlns="http://propay.com/SPS/contracts">
<CaptureTransactionResult xmlns:a="http://propay.com/SPS/types" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:RequestResult>
<a:ResultCode>00</a:ResultCode>
<a:ResultMessage/>
<a:ResultValue>SUCCESS</a:ResultValue>
</a:RequestResult>
<a:TransactionDetail>
<a:AVSCode>NotPresent</a:AVSCode
<a:AuthorizationCode i:nil="true"/>
<a:CVVResponseCode>NotPresent</a:CVVResponseCode>
<a:CurrencyConversionRate>1</a:CurrencyConversionRate>
<a:CurrencyConvertedAmount>2147483646</a:CurrencyConvertedAmount>
<a:CurrencyConvertedCurrencyCode>USD</a:CurrencyConvertedCurrencyCode>
<a:GrossAmt>2147483646</a:GrossAmt>
<a:GrossAmtLessNetAmt>75161963</a:GrossAmtLessNetAmt>
<a:NetAmt>2072321683</a:NetAmt>
<a:PerTransFee>35</a:PerTransFee>
<a:Rate>3.50</a:Rate>
<a:ResultCode>
<a:ResultCode>00</a:ResultCode>
<a:ResultMessage/>
<a:ResultValue>SUCCESS</a:ResultValue>
</a:ResultCode>
<a:TransactionHistoryId>103271482</a:TransactionHistoryId>
<a:TransactionId>1</a:TransactionId>
<a:TransactionResult>Success</a:TransactionResult>
</a:TransactionDetail>
</CaptureTransactionResult>
</CaptureTransactionResponse>
</s:Body>
</s:Envelope>
Implementation Details
Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Submission

Response Handling

Request Values

Request Element

Type

Max

Required

Notes

Id.AuthenticationToken

String

100 Characters

Authorization

Valid value is a GUID. Value supplied by ProPay. Used to access the API

Id.BillerAccountId

String

16 Characters

Authorization

Value supplied by ProPay. Used to identify the correct collection of tokens.

Amount

Int(64)

Signed Int(64)

Required

The value representing the number of pennies in USD, or the number of [currency] without decimals.

Comment1

String

128 Characters

No

Transaction descriptor. Only passed if supported by the gateway.

Comment2

String

128 Characters

No

Transaction descriptor. Only passed if supported by the gateway.

CurrencyCode

String

3 Characters

Required

ISO 4217 standard 3 character currency code.

MerchantProfileId

Int(64)

Signed Int(64)

Required

Used to specify which processor and merchant account to process the transaction against.

TransactionHistoryId

Int(64)

Signed Int(64)

Required

ProtectPay’s identifier for the transaction to capture.

**This value is returned by AuthorizePaymentMethodTransaction.

 

Response Values

Response Element

Type

Notes

RequestResult.ResultValue

String

The ProtectPay API Method Response Value;

SUCCESS indicates the method completed;

FAILURE indicates the method call failed and the reason is indicated in the ResultCode and ResultMessage

RequestResult.ResultCode

String

The ProtectPay API Method Response Code. See Appendix for possible returned values

RequestResult.ResultMessage

String

The ProtectPay API Method Response Message. See Appendix for possible returned Messages

AuthorizationCode

String

The auth code supplied by the issuing bank.

*Only returned on a successful transaction

AVSCode

String

AVS response produced by gateway

*Only returned if AVS information is supplied and AVS is supported by the gateway.

CurrencyConversionRate

Decimal

The rate for currency conversion used for multi-currency transactions

CurrencyConvertedAmount

Long

Gross converted amount of transaction in the number of [currency] without decimals for multi-currency transactions

CurrencyConvertedCurrencyCode

String

The currency the transaction was converted to for multi-currency transactions

CVVResponseCode

String

 

GrossAmt

Long

Gross amount of transaction of pennies in USD, or the number of [currency] without decimals.

GrossAmtLessNetAmt

Long

Total amount of fees charged; *ProPay Gateway Only

NetAmt

Long

Net amount of transaction after fees charged; *ProPay Gateway Only

PerTransFee

Long

Per transaction fee; *ProPay Gateway Only

Rate

Decimal

Percentage fee; *ProPay Gateway Only

Transaction.ResultCode.ResultValue

String

The result value of the transaction request as reported by the ProtectPay. SUCCESS or FAILURE

Transaction.ResultCode.ResultCode

String

The result code of the transaction request as reported by ProtectPay. See Appendix for possible returned values

Transaction.ResultCode.ResultMessage

String

The result message of the transaction request as reported by ProtectPay. See Appendix for possible returned values

TransactionHistoryId

String

Unique transaction number assigned by ProtectPay.

TransactionId

String

Transaction number assigned by processor (Gateway)

TransactionResult

String

Transaction result as reported by processor (Gateway)