Skip to content

Capture

Info

This transaction type is available for: Cards.

A Capture is used to request clearing for previously authorized funds.

The 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

For the Capture request you should send:

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.merchantterminalIdMax10NumericText
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.
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:
Autorization: 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:

Result codestatusMsgDescriptionAction
HTTP-200SuccessSuccess responsen/a.
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many RequestsThe API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.