Pre-authorized capture
Available for: Cards
Use the pre-authorized capture when the customer is only charged (totally or partially) when goods or services are provided afterwards.
This flow resembles the “one time purchase” flow, but an additional step is required to actually charge the customer for the goods or services – the Capture (please refer to the Backoffice operations for further details).
The Capture can be for the total amount of the purchase, or for part of it, in which case, multiple Captures accepted up to the authorisation’s full amount.
Before you start:
Create the order with the required data and guarantee the following information:
- Include the payment type, amount, currency and payment methods allowed;
- If you are already sure that only Card payment is required, then only include “CARD” in the transaction.paymentMethod list;
- Make sure the transaction.paymentType holds the value “AUTH”
Generate the transaction:
Note that the following request needs an Authorisation Header with the transactionSignature returned from checkout operation.
In this requests, the Bearer Token is replaced by the checkout response transactionSignature.
Here’s an example:
Expected Response:
A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.
The paymentStatus in the response informs on whether the transaction itself was accepted, declined, still pending a final result, or requiring additional action to be taken.
- Success: The authorisation has been processed successfully and the customer funds have been validated.
- Declined: The authorisation has been declined.
- Pending: The final result of the authorisation is not yet known. You will need to inquiry on the status of this transaction until it reaches a final state, or you decide to cancel it.
- Partial: The authorisation is partially accepted, but requires additional actions to the completed (e.g. 3D-Secure authentication). The actionResponse element is provided for instructions on how to proceed.
Make the future capture(s):
A Capture is used to request clearing for previously authorized funds.
A Capture request is performed using a previous preauthorisation (AUTH) payment by referencing its transactionID and sending a POST request over HTTPS to the /payments/{transactionID}/capture endpoint.
Captures can happen in different ways:
- Full, capture the full amount authorized and finish the purchase
- Partial, split the capture over one or several capture requests, up to the total amount authorized
Capture Description
Operation
Operation Type
Operation Method & Endpoint
Operation Description
Observations
Product
Card
Synchronous Call
POST version-id/{original-tx-id}/capture
Requests the financial capture (parcial amount or total amount) related to a previous authorisation.
Capture Request
Location
Data Element
Type
Condition
Description
Path
original-tx-id
String
Mandatory
Original Transaction Id (transaction identification of the original authorization
Request Header
Content-Type
String
Mandatory
application/json
Request Header
authorization
String
Mandatory
Bearer Token. Based on OAuth2 authentication performed in a pre-step.
Request Header
x-ibm-client-id
String
Mandatory
Token that identifies a client organization. It is provided during onboarding process and must be used in every call.
Request Body
merchant
Merchant
Mandatory
Object that defines a Merchant.
Request Body.merchant
terminalId
Max10NumericText
Merchant Terminal Identification.
Request Body.merchant
channel
string
Channel used in the transaction.
Request Body.merchant
merchantTransactionId
string
Unique identifier of the transaction in the merchant perspective.
Request Body
customer
Customer
Mandatory
Object that defines a Customer.
Request Body.customer
customerInfo
CustomerInfo
Mandatory
Object that defines the predefined customer information.
Request Body.customer.customerInfo
customerName
string
Customer name.
Request Body.customer.customerInfo
shippingAdress
Adress
Mandatory
Customer Address. When applicable used for shipping products.
Request Body.customer.customerInfo.shippingAdress
street1
Max70Text
Shipping Address Street
Request Body.customer.customerInfo.shippingAdress
street2
Max70Text
Shipping Address Additional Street
Request Body.customer.customerInfo.shippingAdress
city
Max35Text
Shipping Address city or town.
Request Body.customer.customer.Info.shippingAdress
postcode
Max16Text
Shipping Address Postal Code.
Request Body.customer.customer.Info.shippingAdress
countrySubDivision
Max35Text
Shipping Address Subdivision . Subdivision of a country such as state, region, county.
Request Body.customer.customer.Info.shippingAdress
country
Country Code
Shipping Country Code. Alpha2
Request Body.customer.customerInfo
billingAddress
Address
Mandatory
Customer Billing Address.
Request Body.customer.customerInfo.billingAddress
street1
Max70Text
Billing Address Street.
Request Body.customer.customerInfo.billingAddress
street2
Max70Text
Billing Address Additional Street
Request Body.customer.customerInfo.billingAddress
city
Max35Text
Billing Address city or town.
Request Body.customer.customerInfo.billingAddress
postcode
Max16Text
Billing Address Postal Code.
Request Body.customer.customerInfo.billingAddress
countrySubDivision
Max35Text
Billing Address Subdivision . Subdivision of a country such as state, region, county.
Request Body.customer.customerInfo.billingAddress
country
Country Code
Billing Country Code. Alpha2
Request Body.customer.customerInfo
billingAddressSameAsAddress
Boolean
Flag that identifies that the billing address is the same as the shipping address.
Request Body.customer
extendedInfo
ExtendedInfo
Mandatory
Key Value tuple array.
Request Body.customer.extendedInfo
key
string
Request Body.customer.extendedInfo
value
string
Request Body
transaction
Transaction
Mandatory
Object that defines a transaction.
Request Body.transaction
transactionTimeStamp
ISODateTime
Transaction timestamp.
Request Body.transaction
description
string
Transaction short description.
Request Body.transaction
amount
Amount
Mandatory
Parameter with the value and currency of the transaction.
Request Body.transaction.amount
value
Number (double)
Amount in the transaction.
Request Body.transaction.amount
currency
Currency Code
Currency used in the transaction. Alpha3
Request Body.transaction.amount
settlementPoint
settlementPoints
Optional
Transaction Amount Settlement Points Array
Request Body.transaction.settlementPoint
identifier
Max36Text
Mandatory
Settlement Point Unique Identifier
Request Body.transaction.settlementPoint
amount
Amount
Mandatory
Settlement Point amount with the value and currency of the transaction.
Request Body.transaction.settlementPoint.amount
value
Number (double)
Mandatory
Amount in the transaction.
Request Body.transaction.settlementPoint.amount
currency
Currency Code
Mandatory
Currency used in the transaction. ISO 4217 Alpha-3 Code.
Request Body
originalTransaction
OriginalTransaction
Object that identifies an Original Transaction.
Request Body.originalTransaction
id
string
Original Transaction Identification.
Request Body.originalTransaction
datetime
ISODateTime
Original Transaction Timestamp.
Request Body
saleContext
SaleContext
Mandatory
Object that defines the back office operation sale context.
Request Body.saleContext
splitPayment
SplitPayment
Mandatory
Object that defines the split payment options.
Request Body.saleContext.splitPayment
split
Boolean
Indicates if it is to split or not.
Request Body.saleContext.splitPayment
paymentNumber
Integer
Indicates the Payment Number.
Request Body.saleContext.splitPayment
maxPayments
Integer
Indicates the maximum number of payments.
Request Body
retry
string
Mandatory
Retry counter for repeated invocations.
Request Body.retry
counter
Integer
Counter for the number of retries for repeating invocations.
