Use our Server-to-Server APIs to receive payments directly from your backend and have full control over your checkout experience.

This integration model lets you collect payment data on your side and submit it securely to SIBS Gateway for processing.
Follow the steps below to start accepting payments efficiently and safely.

Step 1: Create an order

When your shopper is ready to pay, you start by creating an order. This triggers a transaction in the system and defines the shopper, merchant, and transaction information needed for payment processing.

The available endpoint destination URL:

Environment	URL	Operation Method & Endpoint	Operation Description
PROD	api.sibsgateway.com	POST api/version-id/payments	Creates a transaction and prepares it for payment processing.
TEST	stargate.qly.site[1|2].sibs.pt	POST api/version-id/payments	Creates a transaction in test environment.

The order creation process requires three main actions:

Action 1: Define the header, add merchant and customer information

Action 2: Add transaction information to your order

Action 3: Complete your order with additional and optional configuration

Action 1: Define the header, add merchant and customer information

In this action, you define the headers required for authentication and provide the merchant and shopper information needed to initiate the transaction.

This ensures the API can correctly identify the merchant, validate permissions, and associate the shopper with the order.
Check below the full description of the required data to start creating your order.

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 for authentication.	Bearer xxxxxxxx
x-ibm-client-id	string	Mandatory	Token identifying the client organization, provided during onboarding.	123456789

Request parameters

Below are the core objects required for a standard server-to-server checkout integration. Each object is shown with its main fields, and nested subfields are presented using dot notation for clarity. Optional metadata is grouped together to avoid repetition.

Field	Type	Condition	Description
merchant	object	Mandatory	Merchant details. Optional element to query transaction status.
customer	object	Mandatory	Customer details.
transaction	object	Mandatory	Transaction details (amount, method, timestamp).
info	object	Mandatory	Customer device and additional info.
extendedInfo	array of key-value	Optional	Key-value tuples for extra merchant info.
customerinfo	Array	Optional	Additional customer metadata in key-value format.

1. Merchant (object) – Mandatory

Merchant details are required to identify and process the transaction.

Field	Type	Condition	Description	Example
merchant	object	Mandatory	Merchant object container.	–
merchant.terminalID	numeric (≤10)	Mandatory	Merchant Terminal Identification	24
merchant.channel	string	Mandatory	Merchant channel	Web
merchant.merchantTransactionID	string (≤1000)	Mandatory	Unique transaction ID	Order_20260219_001
merchant.transactionDescription	String (≤4000)	Optional	Description of transaction	Payment for order #001
merchant.shopURL	string	Optional	Merchant website URL used for transaction-related redirects	https://myshop.pl

2. Customer (object) – Mandatory

Customer details include personal, billing, and shipping information.

Field	Type	Condition	Description	Example
customer	object	Mandatory	Customer object container	–
customer.customerInfo	object	Mandatory	Predefined customer information	–
customer.shippingAddress	object	Optional	Customer shipping address	–
customer.shippingAddress	object	Optional	Customer billing address	–
customer.billingAddressSameAsShippingAddress	boolean	Optional	Flag indicating if billing address is same as shipping	True

2.1 Customer Info (subobject) – Mandatory

Field	Type	Condition	Description	Example
customer.customerInfo.customerName	string	Mandatory	Shopper’s full name	Jan Kowalski
customer.customerInfo.customerEmail	string	Mandatory	Shopper’s email	jan.kowalski@example.pl
customer.customerInfo.customerPhone	string	Conditional	Phone number in E.164 format, must start with “+” and maximum 15 digits. Mandatory if paymentMethod is: “MBWY” – “MB Way”. Otherwise, optional for remaining methods.	+48500123456
customer.customerInfo.customerLanguage	string (ISO 639-1)	Conditional	Mandatory if paymentMethod is: “BNCT” – “Bancontact”; “IDEL” – “iDEAL”;”BIZM”-“Bizum”. Otherwise, optional for remaining methods.	PL
customer.customerInfo.shippingAddress	Address	Mandatory	Customer shipping address when applicable	–
customer.customerInfo.billingAddress	Address	Mandatory	Customer billing address	–
customer.customerInfo.billingAddressSameAsAddress	Boolean	Optional	True if billing address equals shipping	True

2.2 Shipping Address (subobject) – Mandatory when applicable

Used when physical goods are involved.

Field	Type	Condition	Description	Example
customer.shippingAddress.street1	string (≤70)	Mandatory	Street line 1	ul. Marszałkowska 10
customer.shippingAddress.street2	string (≤70)	Optional	Street line 2	Apartment 5
customer.shippingAddress.city	string (≤35)	Mandatory	City / town	Warszawa
customer.shippingAddress.postcode	string (≤16)	Mandatory	Postal code	00-001
customer.shippingAddress.countrySubDivision	string (≤35, ISO 3166-1 Alpha 2)	Optional	State / Province code	PL
customer.shippingAddress.country	string (ISO 3166-1 Alpha 2)	Mandatory	Country code	PL

2.3 Billing Address (subobject) – Optional

Field	Type	Condition	Description	Example
customer.billingAddress.street1	string (≤70)	Mandatory	Street line 1	ul. Marszałkowska 10
customer.billingAddress.street2	string (≤70)	Optional	Street line 2	–
customer.billingAddress.city	string (≤35)	Mandatory	City / town	Warszawa
customer.billingAddress.postcode	string (≤16)	Mandatory	Postal code	00-001
customer.billingAddress.countrySubDivision	string (≤35, ISO 3166-1 Alpha 2)	Optional	State / Province code	PL
customer.billingAddress.country	string	Conditional	Billing country code (ISO 3166-1 Alpha 2)	PL

3. Info (object) – Mandatory

Additional contextual information about the transaction, including device data.

Field	Type	Condition	Description	Example
info	object	Mandatory	Additional contextual information about the transaction.	–
info.deviceInfo	object	Mandatory	Customer device information.	–

3.1 Device Info (subobject) – Mandatory

Field	Type	Condition	Description	Example
info.deviceInfo.browserAcceptHeader	string	Optional	Browser Accept Header	text/html
info.deviceInfo.browserJavaEnabled	string	Optional	Browser Java Enabled	True
info.deviceInfo.browserJavascriptEnabled	string	Optional	Browser Javascript Enabled	True
info.deviceInfo.browserLanguage	string	Optional	Browser Language	en-US
info.deviceInfo.browserColorDepth	string	Optional	Browser Color Depth	24
info.deviceInfo.browserScreenHeight	string	Optional	Browser Screen Height	1080
info.deviceInfo.browserScreenWidth	string	Optional	Browser Screen Width	1920
info.deviceInfo.browserTZ	string	Optional	Browser Time Zone	GMT+1
info.deviceInfo.browserUserAgent	string	Optional	Browser User Agent	Mozilla/5.0
info.deviceInfo.systemFamily	string	Optional	System Family	Windows
info.deviceInfo.systemVersion	string	Optional	System Version	10
info.deviceInfo.systemArchitecture	string	Optional	System Architecture	x64
info.deviceInfo.deviceManufacturer	string	Optional	Device Manufacturer	Dell
info.deviceInfo.deviceModel	string	Optional	Device Model	XPS 15
info.deviceInfo.deviceID	string	Optional	Device Unique ID	12345-6789
info.deviceInfo.applicationName	string	Optional	Application Name Note: Form must fill this field with “Form:applcationName”.	Form:Edge
info.deviceInfo.applicationVersion	string	Optional	Application Version Note: Form must fill this field with “formVersion:applicationVersion”.	2.0:130
info.deviceInfo.geoLocalization	string	Optional	Geolocation	52.2297,21.0122
info.deviceInfo.ipAddress	string	Optional	IP Address	192.168.1.1

Optional Generic Extension Fields

The following fields allow merchants to provide additional contextual or custom metadata not covered by the core schema. These fields are optional and may be used to extend transaction or customer information in a flexible key-value structure.

extendedInfo (object) – Optional

Generic key-value data related to the transaction.

Field	Type	Condition	Description	Example
extendedInfo	Array of key-value	Optional	Container for additional merchant information.	extendedInfo
extendedInfo.key	string	Mandatory	Extension property key.	loyaltyId
extendedInfo.value	string	Mandatory	Extension property value.	LTY-998877

customerInfo (subobject) – Optional

Additional customer metadata provided as key-value pairs.

Field	Type	Condition	Description	Example
customerInfo	Array of key-value	Optional	Container for additional customer metadata.	–
customerInfo.key	string	Mandatory	Customer metadata key.	internalSegment
customerInfo .value	string	Mandatory	Customer metadata value.	VIP

Action 2: Add Transaction Information

This action defines the transaction itself, including the amount, payment method, timestamp, and other attributes necessary to process the payment correctly.
Now it is time to include your transaction information based on the payment methods you want to render in your paywall.

transaction (object) – Mandatory

Field	Type	Condition	Description	Example
transaction	object	Mandatory	Transaction details (amount, method, timestamp).	–
transaction.transactionTimeStamp	ISODateTime	Mandatory	Transaction creation timestamp	2026-02-19T15:00:00.000Z
transaction.description	string (<=70)	Mandatory	Transaction short description	Payment for Order #20260220
transaction.moto	boolean	Mandatory	Indicates whether the transaction is a Mail Order / Telephone Order (MOTO) transaction.	False
transaction.paymentType	string	Mandatory	Type of payment. allowed values: “PURS”– Purchase “AUTH”– Authorization	PURS (Purchase)
transaction.paymentMethod	array	Mandatory	Possible values are: “CARD” – Card “TOKEN” – Token “PAY_BY_LINK”- Pay by Link “BLIK” – BLIK “XPAY” – xPay “IDEL” – Ideal “BNCT” – Bancontact “SPDD” – SEPA Direct Debit “CRTB” – Cartes Bancaires “MBWY” – “MB WAY” “BIZM” – “Bizum”	[“CARD”,”BLIK”,”TOKEN”]
transaction.amount	object	Mandatory	Amount object containing transaction value and currency	–

Amount (object) – Mandatory

Field	Type	Condition	Description	Example
transaction.amount	object	Mandatory	Transaction amount and currency	–
transaction.amount.value	double	Mandatory	Amount of transaction	50.5
transaction.amount.currency	string	Mandatory	Currency ISO 4217	PLN

Action 3: Additional Configuration

In this step, we show you that there is plenty of optional information that you add to complete your order creation. Please check below the additional information based on some use cases:

Here is an example of how to create an order:

Request body:

</> JSON
{
  "merchant": {
    "terminalId": 47215,
    "channel": "web",
    "merchantTransactionId": "ORDER_20260309_001",
    "transactionDescription": "Payment for order #1001",
    "shopURL": "https://myshop.com"
  },
  "customer": {
    "customerInfo": {
      "customerName": "Jan Kowalski",
      "customerEmail": "jan.kowalski@example.com",
      "customerPhone": "+48500123456",
      "customerLanguage": "PL"
    },
    "shippingAddress": {
      "street1": "Marszalkowska 10",
      "street2": "Apartment 5",
      "city": "Warsaw",
      "postcode": "00-001",
      "countrySubDivision": "PL",
      "country": "PL"
    },
    "billingAddressSameAsShippingAddress": true
  },
  "transaction": {
    "transactionTimestamp": "2026-03-09T14:30:00.000Z",
    "description": "Order payment",
    "moto": false,
    "paymentType": "PURS",
    "paymentMethod": [
      "CARD",
      "BLIK"
    ],
    "amount": {
      "value": 50.50,
      "currency": "EUR"
    }
  },
  "info": {
    "deviceInfo": {
      "browserAcceptHeader": "text/html",
      "browserJavaEnabled": "true",
      "browserJavascriptEnabled": "true",
      "browserLanguage": "en-US",
      "browserColorDepth": "24",
      "browserScreenHeight": "1080",
      "browserScreenWidth": "1920",
      "browserTZ": "GMT+1",
      "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "systemFamily": "Windows",
      "systemVersion": "10",
      "systemArchitecture": "x64",
      "deviceManufacturer": "Dell",
      "deviceModel": "XPS 15",
      "deviceID": "12345-67890",
      "applicationName": "MyShopCheckout",
      "applicationVersion": "1.0",
      "geoLocalization": "52.2297,21.0122",
      "ipAddress": "192.168.1.10"
    }
  },
  "extendedInfo": [
    {
      "key": "loyaltyId",
      "value": "LTY-998877"
    }
  ]
}

Step 2: Get the response

After submitting the POST /api/{version-id}/payments request, SIBS Gateway returns a structured JSON response containing the transaction status, technical execution details, available payment methods and security elements.

At this stage, your backend should:

• Validate the processing status
• Validate the transactionSignature
• Store the transaction identifiers
• Prepare the frontend checkout experience according to the returned data

Response Parameters

The following table describes the main fields returned in the API response.

Field	Type	Condition	Description	Example
returnStatus	Object	Mandatory	Object that defines the status of the processed transaction.	–
transactionID	string (<=36)	Conditional	Unique identifier assigned to the transaction by SIBS Gateway.	42f59038f3f14e618d091da8bf3b717e9999
transactionSignature	string	Conditional	Digital signature of the transaction response. You must validate this signature in your backend to ensure response integrity and authenticity.	eyJ0eElkIjoiZzB6Q…
amount	Object	Conditional	Object that defines the transaction amount and currency.	–
merchant	Object	Conditional	Object that contains the merchant identification and transaction configuration data required for payment processing.	–
actionResponse	Object	Optional	Object returned when additional action is required before payment completion.	–
paymentMethodList	Array of string	Mandatory	List of available payment methods for this order. Possible values are: “CARD” – Card “TOKEN” – Token “PAY_BY_LINK”- Pay by Link “BLIK” – BLIK “XPAY” – xPay “IDEL” – Ideal “BNCT” – Bancontact; “SPDD” – SEPA Direct Debit “CRTB” – Cartes Bancaires “MBWY” – “MB WAY” “BIZM” – “Bizum”	[“CARD”,”BLIK”]
tokenList	Array of Object	Conditional	List of payment tokens available for the shopper.	–
expiry	string (ISODateTime)	Mandatory	Expiration date and time of the order.	2026-02-19T20:30:00Z
execution	Object	Mandatory	Contains technical timestamps related to the processing of the request.	–
regulationList	Array of Object	Mandatory	List of regulations and legal information applied to the service.	–
actionResponse	Object	Optional	Returned only when an additional action is required to complete the transaction.	–

returnStatus (Object) – Mandatory

This object provides the result of the processed transaction.

Field	Type	Condition	Description	Example
returnStatus	Object	Mandatory	Object that defines the status of the processed transaction.	–
returnStatus.statusCode	string	Mandatory	Transaction status code. “000” indicates success. Any other value represents an error.	000
returnStatus.statusMsg	string	Mandatory	Message of the processed transaction status.	Success
returnStatus.statusDescription	string	Mandatory	Description of the processed transaction status.	Transaction created successfully

amount (object) – Conditional

Returned when the transaction amount information is available in the response.

Field	Type	Condition	Description	Example
amount	object	Conditional	Object that defines the transaction amount and currency.	–
amount.value	number (double)	Mandatory	Transaction amount value.	50.5
amount.currency	string (ISO 4217 Alpha-3)	Mandatory	Currency used in the transaction.	PLN

merchant (object) – Conditional

This object contains merchant identification and configuration details related to the transaction.

Field	Type	Condition	Description	Example
merchant	object	Conditional	Object that contains the merchant identification and transaction configuration data required for payment processing.	–
merchant.terminalId	string (<=10)	Mandatory	Merchant terminal identification.	47215
merchant.channel	string	Mandatory	Merchant Channel	Web
merchant.merchantTransactionId	string (<=36)	Mandatory	Unique transaction identifier used and provided by the merchant.	Order_20260219_001
merchant.websiteAddress	string	Mandatory	Merchant website URL. Merchant website address configured during onboarding (Acceptor configuration). This value is static and does not change per transaction.	myshop.pl
merchant.shopURL	string	Optional	Merchant URL used for redirects during the transaction flow. If returned, it reflects the value originally provided in the request.	https://myshop.pl/status

execution (object) – Mandatory

Technical timestamps that indicate when the request started and when the response was generated.

Field	Type	Condition	Description	Example
execution	object	Mandatory	Contains technical timestamps related to the processing of the request.	–
execution.startTime	string (ISODateTime)	Yes	Time when the API accepted the request.	2026-02-19T13:41:01.626Z
execution.endTime	string (ISODateTime)	Yes	Time when the API responded to the request.	2026-02-19T13:41:02.105Z

regulationList (object) – Mandatory

This object contains regulatory and compliance information that must be presented to the shopper depending on the service configuration.

Field	Type	Condition	Description	Example
regulationList	Array of Object	Mandatory	List of regulations and legal information applied to the service.	–
regulationList.identification	string	Mandatory	Unique identifier of the regulatory element as configured for the service.	REG_001
regulationList.type	string (RegulationType)	Mandatory	Type of regulatory element. Possible values are: ACCEPTANCE – Acceptance statement COMPLAINTS – Complaints information CERTIFICATIONS – Certifications or compliance references ACQUIRER_NAME – Acquirer identification ACCQUIRER_LOGO – Acquirer logo resource VISA_NETWORK_LOGO – Visa network logo MASTERCARD_NETWORK_ LOGO – Mastercard network logo	ACCEPTANCE
regulationList.language	string (ISO 639-1)	Mandatory	Language associated with the regulatory element. Must follow ISO 639-1 format.	PL
regulationList.label	string	Optional	Informational text associated with the regulatory element.	By proceeding, you accept the terms and conditions.
regulationList.regulationURL	string	Optional	Terms and conditions configured for the Service.	https://merchant.com/terms
regulationList.logoURL	string	Optional	URL of a logo resource associated with the regulatory element.	https://gateway.com/logo.png

Response example:

{
  "returnStatus": {
    "statusCode": "000",
    "statusMsg": "SUCCESS",
    "statusDescription": "TRANSACTION CREATED SUCCESSFULLY"
  },
  "transactionID": "42f59038f3f14e618d091da8bf3b717e9999",
  "transactionSignature": "eyJ0eElkIjoiZzB6Q...",
  "amount": {
    "value": 50.50,
    "currency": "EUR"
  },
  "merchant": {
    "terminalId": 47215,
    "channel": "WEB",
    "merchantTransactionId": "ORDER_20260309_001",
    "transactionDescription": "PAYMENT FOR ORDER #1001",
    "websiteAddress": "MYSHOP.COM",
    "shopURL": "HTTPS://MYSHOP.COM/STATUS"
  },
  "paymentMethodList": ["CARD", "BLIK"],
  "tokenList": [],
  "expiry": "2026-03-09T20:30:00Z",
  "execution": {
    "startTime": "2026-03-09T14:30:00.000Z",
    "endTime": "2026-03-09T14:30:01.200Z"
  },
  "regulationList": [
    {
      "identification": "REG_001",
      "type": "ACCEPTANCE",
      "language": "PL",
      "label": "By proceeding, you accept the terms and conditions.",
      "regulationURL": "https://merchant.com/terms",
      "logoURL": "https://gateway.com/logo.png"
    }
  ]
}

actionResponse (object) – Optional

In some payment scenarios, the transaction cannot be completed immediately and requires an additional step before the final result is available.

When this happens, the API returns the actionResponse object. This object contains the information your backend needs to execute the next step required to continue the payment flow.

Until the action described in this object is executed, the transaction will remain in a pending state.

If the action is not performed before the order expiration time, the transaction will expire and will no longer be processed.

Field	Type	Condition	Description	Example
actionResponse	object	Optional	Returned only when an additional action is required to complete the transaction.	–
actionResponse.data	object	Mandatory	Container for additional action details.	–

actionResponse.data – Optional

This object contains the technical information required to perform the additional step in the payment flow.

Field	Type	Condition	Description	Example
actionResponse.data	object	Optional	Container for additional action details.	–
actionResponse.data.url	string	Optional	Endpoint that must be called to perform the additional step required to complete the payment. The transaction remains pending until this step is successfully executed.	–
actionResponse.data.params	Array	Optional	Parameters that must be sent when calling the provided endpoint to complete the required additional action.	–

actionResponse.data.params – Array

If parameters are required to execute the additional action, they will be returned in the params array.

Each element in this array represents a parameter that must be included in the request sent to the provided endpoint.

Field	Type	Condition	Description	Example
actionResponse.data.params	Array	Optional	List of parameters required to execute the additional action. Each entry is represented as an object.	–
actionResponse.data.params.parameter	object	Optional	Object representing a single parameter required for the additional action.	–

actionResponse.data.params.parameter (object) – Optional

Each parameter object contains the name of the parameter and the value that must be submitted when calling the action endpoint.

Field	Type	Condition	Description	Example
actionResponse. params.parameter.name	string	Optional	Parameter name required by the action endpoint.	–
actionResponse. params.parameter.data	string	Optional	Value to be submitted for the parameter defined above. Content depends on the requested action.	–

actionResponse Example

The following example shows a response that requires an additional action before the payment can continue.

{
  "actionResponse": {
    "url": "https://acs.gateway.com/3ds",
    "params": [
      {
        "name": "PaReq",
        "value": "eJxVUttygjAQ..."
      },
      {
        "name": "TermUrl",
        "value": "https://merchant.com/3ds/callback"
      }
    ]
  }
}

HTTP Status Codes

The API returns standard HTTP status codes together with a structured returnStatus object in the response body.

Merchants must always validate both the HTTP status code and the returnStatus.statusCode before proceeding.

The response contains a statusMsg that can assume different values:

Result code	statusMsg	Description	Action
HTTP-200	Success	Success response	n/a
HTTP-400	Bad Request	The JSON payload does not match 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 does not match 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.

Step 3: Make a payment

After you create and submit the order with the shopper’s payment details, and he chooses to pay with a payment method that requires a redirection, you need to make a payment request to SIBS Gateway.

Check the instruction on how to make payment with each type of payment method:

Payment Method	Description
Card	Accept payments using Visa, Mastercard, and co-branded cards. Suitable for most use cases and supports standard authorization flows.
Pay by Link	Allows customers to complete payments directly through their bank account using a secure redirection flow.
BLIK	Popular mobile payment method in Poland, enabling instant payments using a one-time code generated in the banking app.
Apple Pay & Google Pay	Digital wallet for instant checkout
iDEAL | Wero	Bank-based payment method widely used in the Netherlands, enabling direct account-to-account transfers.
Bancontact	Local payment method in Belgium, commonly used for card-based and bank-linked payments.
SEPA Direct Debit	Enables merchants to collect payments directly from a customer’s bank account within the SEPA zone.
Cartes Bancaires	French domestic card scheme, commonly used alongside international card networks.
MB WAY	Mobile wallet widely used in Portugal, allowing customers to authorize payments through their mobile phone number and app.
Bizum	Instant mobile payment method in Spain, allowing transfers between bank accounts using a phone number.