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.
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 Authorization Header with the transactionSignature returned from checkout operation.
In this request, the Bearer Token is replaced by the checkout response transactionSignature.
Header parameters
Request parameters
Here’s an example:
{
"cardInfo": {
"PAN": "5236410030000927",
"secureCode": "776",
"validationDate": "2026-05-26T00:00:00.000Z",
"cardholderName": "Jane Smith",
"createToken": false
}
}
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.
- 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.
- Declined: The authorisation has been declined.
- 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 pre-authorisation (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 |
---|---|---|---|
Card | Synchronous Call | POST version-id/{original-tx-id}/capture | Requests the financial capture (partial 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 | Mandatory | Unique identifier of the transaction in the merchant perspective. |
Request Body | transaction | Transaction | Mandatory | Object that defines a transaction. |
Request Body.transaction | transactionTimeStamp | ISODateTime | Mandatory | Transaction timestamp. |
Request Body.transaction | description | String | Mandatory | 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) | Mandatory | Amount in the transaction. |
Request Body.transaction.amount | currency | Currency code | Mandatory | Currency used in the transaction. Alpha3 |
Request Body | originalTransaction | OriginalTransaction | Mandatory | Object that identifies an Original Transaction. |
Request Body.originalTransaction | id | String | Mandatory | Original Transaction Identification. |
Here you can see a Capture request example:
{
"merchant": {
"terminalId": {{TerminalID}},
"channel": "web",
"merchantTransactionId": "BO_Order Id: "
},
"transaction": {
"transactionTimestamp": "{{trxDatetime}}",
"description": "Transaction short description",
"amount": {
"value": 1,
"currency": "PLN"
},
"originalTransaction": {
"id": "{{originalTransactionId}}"
}
}
}
The response below, will include the transaction ID, which you can use to check the status.
{
"merchant": {
"terminalId": "101776",
"merchantTransactionId": "BO_Order Id: ",
"merchantTransactionTimestamp": "2023-06-20T11:15:57.040Z"
},
"transactionTimestamp": "2023-06-20T11:16:14.988Z",
"amount": {
"value": "1",
"currency": "PLN"
},
"transactionID": "RW5vBMHj4RhQWFRc0GvS",
"execution": {
"startTime": "2023-06-20T11:15:57.206Z",
"endTime": "2023-06-20T11:16:15.100Z"
},
"paymentStatus": "Success",
"returnStatus": {
"statusCode": "000",
"statusMsg": "Success",
"statusDescription": "Success."
}
}
Afterwards, once the payment has been processed, you can check the status of your transaction making a GET request.
The Authorisation HTTP header is set to the Bearer token as it was used in the initial Checkout.
Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
Request Headers:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.
Here are some examples of the possible result codes: