A Capture is used to complete a previously authorized payment by capturing all or part of the authorized amount.

To perform a Capture, send a POST request to the /payments/{original-tx-id}/capture endpoint, referencing the original Authorization transactionID.

The following capture operations are supported:

Capture Type	Description
Full Capture	Captures the full authorized amount in a single request.
Partial Capture	Captures part of the authorized amount. Multiple Capture requests may be performed until the total authorized amount is reached.

Capture operation:

Operation	Operation Type	Operation Method & Endpoint	Description
Card	Synchronous Call	POST /payments/{original-tx-id}/capture	Requests the financial capture (partial or full amount) of a previous Authorization transaction.

Header parameters:

Field	Type	Required	Description	Example
Content-Type	string	Mandatory	Defines the content type of the request.	application/json
Authorization	string	Mandatory	Bearer token obtained during the OAuth2 authentication process.	Bearer eyJhbGc…
x-ibm-client-id	string	Mandatory	Token identifying the client organization. This value is provided during the onboarding process and must be included in every API request.	123456789

Request parameters

The following objects define the Capture request structure. Depending on the transaction scenario, some objects may have specific usage conditions. Nested fields are represented using dot notation for readability. 

All examples shown in this documentation are illustrative. 

Merchants must provide valid values according to their integration, business rules and payment configuration. 

Merchant (object) – Mandatory 

Merchant information used to identify the transaction.

Field	Type	Condition	Description	Example
Request Body.merchant	object	Mandatory	Merchant object container.	—
merchant.terminalId	string (Max10NumericText)	Mandatory	Merchant Terminal Identification.	24
merchant.channel	string	Mandatory	Merchant channel.	web
merchant.transactionId	string (Max1000Text)	Mandatory	Unique identifier defined by the merchant. This field must not contain the semicolon (;) character, as it is used as a column delimiter in EOD and reporting files.	ORDER_20260309_001
merchant.transactionDescription	string (Max4000Text)	Optional	Merchant transaction description. This field must not contain the semicolon (;) character, as it is used as a column delimiter in EOD and reporting files.	Payment for order #1001

Customer (object) – Mandatory

Customer information associated with the Capture request. 

Field	Type	Condition	Description	Example
Request Body.customer	object	Mandatory	Customer object container.	—
customer.customerInfo	object	Mandatory	Object containing predefined customer information.	—
customer.customerInfo.customerName	string	Optional	Customer name.	John Smith
customer.customerInfo.shippingAddress	object	Mandatory	Customer shipping address.	—
customer.customerInfo.shippingAddress.street1	string (Max70Text)	Optional	Shipping street address.	Baker Street 221B
customer.customerInfo.shippingAddress.street2	string (Max70Text)	Optional	Additional shipping address information.	Apartment 5
customer.customerInfo.shippingAddress.city	string (Max35Text)	Optional	Shipping city or town.	Warsaw
customer.customerInfo.shippingAddress.postcode	string (Max16Text)	Optional	Shipping postal code.	00-001
customer.customerInfo.shippingAddress.countrySubDivisio	string (Max35Text)	Optional	Shipping subdivision (state, region or county).	Mazowieckie
customer.customerInfo.shippingAddress.country	Country Code (Alpha-2)	Optional	Shipping country code.	PL
customer.customerInfo.billingAddress	object	Mandatory	Customer billing address.	—
customer.customerInfo.billingAddress.street1	string (Max70Text)	Optional	Billing street address.	Baker Street 221B
customer.customerInfo.billingAddress.street2	string (Max70Text)	Optional	Additional billing address information.	Apartment 5
customer.customerInfo.billingAddress.city	string (Max35Text)	Optional	Billing city or town.	Warsaw
customer.customerInfo.billingAddress.postcode	string (Max16Text)	Optional	Billing postal code.	00-001
customer.customerInfo.billingAddress.countrySubDivision	string (Max35Text)	Optional	Billing subdivision (state, region or county).	Mazowieckie
customer.customerInfo.billingAddress.country	Country Code (Alpha-2)	Optional	Billing country code.	PL
customer.customerInfo.billingAddressSameAsAddress	boolean	Optional	Indicates whether the billing address is the same as the shipping address.	true
customer.extendedInfo	array	Mandatory	Collection of merchant-defined key-value pairs.	—
customer.extendedInfo.key	string	Optional	Key name.	loyaltyLevel
customer.extendedInfo.value	string	Optional	Key value.	Gold

Transaction (object) – Mandatory

Transaction details associated with the Capture request. 

Field	Type	Condition	Description	Example
Request Body.transaction	object	Mandatory	Transaction object container.	–
transaction.transactionTimestamp	string (ISODateTime)	Mandatory	Transaction timestamp.	2026-03-09T14:30:15.123Z
transaction.description	string	Mandatory	Short description of the transaction.	This is a capture request
transaction.amount	object	Mandatory	Transaction amount details.	–
transaction.amount.value	number (double)	Mandatory	Transaction amount.	10
transaction.amount.currency	Currency Code (Alpha-3)	Mandatory	Transaction currency using the ISO 4217 Alpha-3 code.	PLN
transaction.settlementPoint	settlementPoints	Optional	Transaction Amount Settlement Points array.	–
transaction.settlementPoint.id	string (Max36Text)	Mandatory	Settlement Point unique identifier.	SP001
transaction.settlementPoint.amount	object	Mandatory	Settlement Point amount details.	–
transaction.settlementPoint.amount.value	number (double)	Mandatory	Settlement Point amount.	10
transaction.settlementPoint.amount.currency	Currency Code (Alpha-3)	Mandatory	Settlement Point currency using the ISO 4217 Alpha-3 code.	PLN
transaction.cart	cart	Conditional	Array of SKUs to be captured. Must be used for partial Capture operations processed with Buy Now Pay Later payment methods.	–
		Mandatory
		Mandatory

</>JSON 
{ 
  "merchant": { 
    "terminalId": 24, 
    "channel": "web", 
    "merchantTransactionId": "BO_Order Id: c9876bcasd", 
    "transactionDescription": "Payment for order #1001" 
  }, 
  "transaction": { 
    "transactionTimestamp": "2022-05-29T18:23:41.367Z", 
    "description": "This is a capture request", 
    "amount": { 
      "value": 10, 
      "currency": "PLN" 
    }, 
    "originalTransaction": { 
      "id": "mvuy3dh3wucpsi4389fh" 
    } 
  } 
} 

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.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 code	statusMsg	Description	Action
HTTP-200	Success	Success response	n/a.
HTTP-400	Bad Request	The 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-401	Unauthorized	On 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-403	Forbidden	The 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-405	Method Not Allowed	The HTTP Method used is not matching any of the API definitions available.	Please check in API Market for the correct HTTP Method.
HTTP-429	Too Many Requests	The API calls rate limit has been exceeded.	Please check in API Market for information on the rate limits that apply to the API.
HTTP-500	Internal Server Error	The 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-503	Service Unavailable	The 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.