Skip to content

Pre-authorized capture

Info

This transaction type is 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.

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
Content-type

string

Mandatory

application/json

Show more
Authorization

string

Mandatory

Bearer Token. Based on OAuth2 authentication performed in a pre-step.

Show more
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.

Show more
Request parameters
cardInfo

object

Mandatory

Object that defines the payment operation request fields.

Show more
PAN

string <= 40 characters

Optional

The Primary Account Number (credit card number).

Show more
secureCode

string <= 40 characters

Optional

The security code (CVV/CVC) associated with the credit card.

Show more
validationDate

ISODateTime

Mandatory

The expiration date of the credit card.

Show more
cardholderName

string

Mandatory

The name of the cardholder as it appears on the credit card.

Show more
createToken

boolean

Mandatory

A flag indicating whether to create a token for future use or not (true/false).

Show more
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:
OperationOperation TypeOperation Method & EndpointOperation Description
CardSynchronous CallPOST version-id/{original-tx-id}/captureRequests the financial capture (partial amount or total amount) related to a previous authorisation.
Capture Request:
LocationData ElementTypeConditionDescription
Pathoriginal-tx-idStringMandatoryOriginal Transaction Id (transaction identification of the original authorization).
Request HeaderContent-TypeStringMandatoryapplication/json. 
Request HeaderauthorizationStringMandatoryBearer Token. Based on OAuth2 authentication performed in a pre-step.
Request Headerx-ibm-client-idStringMandatoryToken that identifies a client organization. It is provided during onboarding process and must be used in every call.
Request BodymerchantMerchantMandatoryObject that defines a Merchant.
Request Body.merchantterminalIdMax10NumericTextMerchant Terminal Identification.
Request Body.merchantchannelStringChannel used in the transaction.
Request Body.merchantmerchantTransactionIdStringMandatoryUnique identifier of the transaction in the merchant perspective.
Request BodytransactionTransactionMandatoryObject that defines a transaction.
Request Body.transactiontransactionTimeStampISODateTimeMandatoryTransaction timestamp.
Request Body.transactiondescriptionStringMandatoryTransaction short description.
Request Body.transactionamountAmountMandatoryParameter with the value and currency of the transaction.
Request Body.transaction.amountvalueNumber (double)MandatoryAmount in the transaction.
Request Body.transaction.amountcurrencyCurrency codeMandatoryCurrency used in the transaction. Alpha3
Request BodyoriginalTransactionOriginalTransactionMandatoryObject that identifies an Original Transaction.
Request Body.originalTransactionidStringMandatoryOriginal 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: