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

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:

Capture Request:

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: