Capture Externally Authorized Payments

Authorize payments in an external system, then capture the payment in Salesforce Billing using our Capture Transaction API methods. You can then use Salesforce Billing to manage the payment lifecycle and settle invoices.

Available in: Salesforce Billing Winter '21 and later

Delayed capture is useful when the payment is authorized at the time of sale and settled after an event occurs. For example, you can capture a payment after a subscription is provisioned or an item is delivered.

Our Capture Payment API works out of the box with the Salesforce Billing Cybersource gateway integration package. Customers using other payment gateways must work with their payment gateway vendors to extend the gateway integration packages to the Capture Payment API.

Important

Managing Payment Authorizations

Salesforce Billing doesn’t process payment authorizations, but you can store information from an external authorization in a Salesforce Billing payment authorization record. To store external authorization information in Salesforce, add information from the external authorization to the following fields in the Salesforce Billing payment authorization record:

Account ID
Original Amount
Currency ISO Code (for multi-currency orgs only)
Payment Gateway ID
- Use the ID of the Salesforce Billing payment gateway record that you use for storing payment capture information. The payment gateway record must have the same merchant credentials used to process the external payment authorization.
Gateway Reference Number
- The payment gateway supplies the reference number.
Status this field must have the value Processed

Calling the Capture Transaction API

After you’ve created a payment authorization, you can pass it to the Capture Transaction API. To call the Capture Transaction API, add the following method to your PaymentGateway Apex class.

1List<blng.OutputResult> result = blng.TransactionAPI.captureTransaction(lcip);

The CaptureTransaction API accepts information through the CaptureInputParameter class.

Table 1. CaptureInputParameter Parameters
Parameter	Description	Type	Required
PaymentAuthorization	ID of the payment authorization record from Salesforce Billing.	ID	Yes
captureAmount	Amount of payment to capture from the payment.	Decimal	Yes
additionalParameters	If your capture request requires more information, you can provide a map of additional key-value pairs to the gateway adapter	Map<String, String>	No

The CaptureOutputResult class returns the results of your capture request. If you successfully capture the payment, Salesforce Billing creates a posted payment record related to your payment authorization. The CaptureTransaction API also sends a capture success message. If the capture fails, the CaptureTransaction API sends a capture failure message.

Table 2. CaptureOutputResult Parameters
Parameter	Description
isSuccess	Shows whether the payment capture request succeeded.
paymentID	The Salesforce Billing payment record that the CaptureAPI created as a result of successfully capturing a payment from the gateway.
paymentTransactionID	The Salesforce Billing payment transaction record containing information about the gateway interaction for the capture request.
errorMessage	If the payment capture was unsuccessful, contains information about the error.

Permissions

To perform a capture transaction, users require access to the following fields.

Payment

Write access on the following fields:

Account
Amount
Status
Payment Authorization
Payment Gateway
Payment Transaction
Payment Gateway ID

Payment Transaction

Write access on the following fields:

Account
Amount
Type
Source Transaction ID
Gateway Request
Gateway Response
Payment Gateway
Gateway Status
Response
Response Code
Response Message
Payment Gateway ID
Gateway Date
Status

Referenced Classes

Example

Request

In this example, CaptureInputParameter receives the payment authorization record from Salesforce Billing, a payment capture amount of 4.23, and additional parameters. The parameters are stored in a list and sent to TransactionAPI , which performs the payment capture. CaptureOutputResult contains information about the capture.

1String authId = 'a1wxxxxxxxxxxxxxxx';
2Map<String, Schema.SObjectField> fieldMap = blng__PaymentAuthorization__c.sObjectType.getDescribe().fields.getMap();
3Set<String> fieldNames = fieldMap.keySet();
4SObject myrecord = Database.query('select ' + String.join((Iterable<String>)fieldNames, ',') + ' from blng__PaymentAuthorization__c Where Id = \''+authId+'\'');
5Map<String,String> additionalParams = new Map<String,String>();
6additionalParams.put('merchantReferenceCode','demoCapture');
7
8blng.CaptureInputParameter cip = new blng.CaptureInputParameter();
9cip.setPaymentAuthorization((blng__PaymentAuthorization__c)myrecord);
10cip.setAmount(4.23);
11cip.setAdditionalParameters(additionalParams);
12List<blng.CaptureInputParameter> lcip = new List<blng.CaptureInputParameter>();
13lcip.add(cip);
14List<blng.CaptureOutputResult> result = blng.TransactionAPI.captureTransaction(lcip);
15system.debug(result[0]);

Success Response

Following a successful payment capture, CaptureOutputResult returns a success response with the IDs of the payment transaction and payment created in Salesforce Billing.

1[CaptureOutputResult.errorMessage=null, CaptureOutputResult.isSuccess=true, 
2paymentId=a25xxxxxxxxxxxxxxx, paymentTransactionId=a24xxxxxxxxxxxxxxx]

Failure Response

Following a failed payment capture, CaptureOutputResult returns a failure response with an error message and the ID of the payment transaction created in Salesforce Billing. The payment transaction contains information about the failed gateway communication.

1[CaptureOutputResult.errorMessage=Invalid data. c:authRequestID, 
2CaptureOutputResult.isSuccess=false, paymentId=null, paymentTransactionId=a24xxxxxxxxxxxxxxx]

Salesforce Billing Developer Guide