Skip to content

Integration guide

Use our APIs to receive payments and create your own payment form to gain complete control over the appearance and user experience of your checkout page. Follow the instructions below to start accepting payments.

Step 1: Create an order

This step describes how to create an order once your shopper is ready to pay.

The available endpoint destination URL:

EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST api/version-id/paymentsPerforms a request to prepare the checkout required data and returns with the Payment Form.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST api/version-id/paymentsPerforms a request to prepare the checkout required data and returns with the Payment Form.

Regarding the required data to create the order, the process requires only a few 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 information
Action 1: Define the header, add merchant and customer information

Check below the full description of the required data to start creating your order.

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
merchant

object

Mandatory

An optional element to query transaction status.

Show more
terminalID

numeric [<= 10 characters]

Mandatory

Merchant Terminal Identification.

Show more
channel

String

Mandatory

Merchant channel, Possible Value “Web”.

Show more
merchantTransactionID

string

Mandatory

Unique Id used by the Merchant.

Show more
transactionDescription

string

Mandatory

Merchant Transaction Short Description.

Show more
shopURL

string

Mandatory

Merchant Shop URL for redirect purposes.

Show more
websiteAddress

string

Mandatory

Merchant’s website identifier for customer redirection.

Show more
customer

object

Mandatory

Object that defines a customer.

Show more
customerInfo

object

Mandatory

Object that defines the predefined customer information.

Show more
customerName

string

Mandatory

Customer Name.

Show more
customerEmail

string

Mandatory

Customer e-mail

Show more
customerLanguage

language code ISO 639-1

Conditional

Customer language

This element is mandatory if intended payment method is one of the following:

“BNCT” – “Bancontact”;
“GRPY” – “giropay”;
“IDEL” – iDEAL;
“SFRT” – “Sofort”;
“PY24” – “Przelewy24”

Show more
shippingAddress

address

Optional

Customer Address. When applicable used for shipping products.

Show more
street 1

string <= 70 characters

Mandatory

Shipping address street.

Show more
street 2

string <= 70 characters

Mandatory

Shipping address street – additional street.

Show more
city

string <= 35 characters

Mandatory

Shipping address city or town.

Show more
postcode

string <= 16 characters

Mandatory

Shipping address Postal Code.

Show more
countrySubDivision

Country code ISO 3166-1 Alpha 2

Mandatory

Shipping country code.

Show more
billingAddress

Address

Optional

Customer billing address.

Show more
street 1

string <= 70 characters

Mandatory

Shipping address street.

Show more
street 2

string <= 70 characters

Mandatory

Shipping address street – additional street.

Show more
city

string <= 35 characters

Mandatory

Shipping address city or town.

Show more
postcode

string <= 60 characters

Mandatory

Shipping address Postal Code.

Show more
countrySubDivision

country code ISO 3166-1 Alpha 2

Mandatory

Shipping country code.

Show more
billingAddressSameAsShippingAddress

boolean

Optional

Flag to identify if the billing address is the same of shipping address.

Show more
Action 2: Add transactional information to your order

Now it is time to include your transaction information based on the payment methods you want to render in your paywall.

Request parameters: application/json
transaction

object

Mandatory

Object that defines a transaction.

Show more
transactionTimeStamp

ISODateTime

Mandatory

Transaction timestamp.

Show more
description

string <= 70 characters

Mandatory

Transaction short description.

Show more
moto

boolean

Mandatory

Indicates if is a Mail Order Telephone Order.

Show more
paymentType

allowed values:
“PURS” – Purchase
“AUTH” – Authorization

Mandatory

Define the of payment used by the client.

Show more
paymentMethod

allowed values:
“CARD”
“TOKEN”
“PBLKY”
“BLIK”
“XPAY”
“BNPL”
“SFRT”
“GRPY”
“IDEL”
“BNCT”
“PY24”

Mandatory

Method of payment used by the client.

Show more
amount
Mandatory

Parameter with the value and currency of the transaction.

Show more
value

number: Double

Mandatory

Amount in the transaction.

Show more
currency

currency code:
ISO 4217 Alpha-3 Code

Mandatory

Currency used in the transaction.

Show more
Notification

Check how to perform one-time purchase or a pre-authorized capture.

Action 3: Complete your order including additional and optional information

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:
{
 "merchant": {
 "terminalId": 24,
 "channel": "web","merchantTransactionId": "Order Id: 9bzraklk4v",
 "transactionDescription": "transaction short description",
 "shopURL": "https://mytest.e-shop.pl/"
 },
 "transaction": {
 "transactionTimestamp": "2023-05-15T20:11:11.488Z",
 "description": "transaction statement description",
 "moto": false,
 "paymentType": "PURS",
 "amount": {
 "value": 50.5,
 "currency": "PLN"
 },
 "paymentMethod": [
 "CARD",
 "BLIK",
 "PBLKV"
 ]
 }
}

Step 2: Get the response

The response includes a statusMsg, a transactionID, a transactionSignature and the list of available paymentMethodList that you can display.

Response example:
{
 "returnStatus": {
 "statusCode": "000",
 "statusMsg": "Success",
 "statusDescription": "string"
 },
 "transactionID": "42f59038f3f14e618d091da8bf3b717e9999",
 "transactionSignature": "42f59038f3f14e618d091da8bf3b717e9999",
 "amount": {
 "value": 50.50,
 "currency": "PLN"
 },
 "merchant": {
 "terminalId": 47215,
 "channel": "web",
 "merchantTransactionId": "5351136",
 "transactionDescription": "string",
 "shopURL": "string",
 "websiteAddress": "string"
 },
 "paymentMethodList": "",
 "tokenList": []
}

The response contains a statusMsg that can assume different values:

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.

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: