Skip to content

Integration guide

Follow the instructions below to implement the Payment Form and start accepting payments seamlessly.

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.comapi/version-id/paymentsPerforms a request to prepare the checkout required data an returns with the Payment Form.
TESTstargate-cer.qly.site[1|2].sibs.ptapi/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 is simple, and it requires only a few actions:

Action 1: Define the header and add merchant and customer information
Action 2: Add transaction information to your order
Action 3: Complete your order including additional and optional information
Action 1: Define the header and 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
Notification

For logged in users the CustomerName and CustomerEmail elements are Mandatory. This will prevent the user from having to fill them in again in the payment form.

Action 2: Add transaction 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 a one-time purchase or a pre-authorised capture.

Action 3: Add transaction information to your order

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: 5hraff455o",
 "transactionDescription": "transaction short description",
 "shopURL": "https://mytest.e-shop.pl/"
 },
 "transaction": {
 "transactionTimestamp": "2023-05-16T10:33:43.587Z",
 "description": "transaction statement description",
 "moto": false,
 "paymentType": "PURS",
 "amount": {
 "value": 50.5,
 "currency": "PLN"
 },
 "paymentMethod": [
 "CARD",
 "BLIK",
 "PBLKV"
 ]
 }
}

Step 2: Create the payment form

To create the payment form you just need to add the following lines of HTML/Javascript to your page and populate the following variables that you got in response from the first step:

  • The checkout’s transactionID that you got in the response from the first step:
<script src="https://stargate-cer.qly.site1.sibs.pt/assets/js/widget.js?id={transactionID}"></script>

The formContext that you get in response from the first step and a formConfig:

<form class="paymentSPG" spg-context="{formContext}" spg-config="{formConfig}"></form>

The formConfig is necessary for you to be able to create the form correctly.

formConfig -> spg-config=”{formConfig}”
{
 "paymentMethodList": [],
 "amount": {
 "value": 50.50,
 "currency": "PLN"
 },
 "language": "en",
 "redirectUrl": ""
}

The attribute attr.spg-config is a JSON in a string format with the follow parameters:

ParameterTypeAvailable valuesDescription
paymentMethodListString‘CARD’
‘TOKEN’
‘BLIK’
‘PBLKV’
‘XPAY’
Payment methods to show on the form.
Only Payment Methods enabled on your account can be used.
amount{ value: number, currency: string }Transaction amount value.
languageString‘pt’
‘en’
‘pl’
Form language (ISO 639-1 Format).
redirectUrlStringURL where the user should be redirected at the end of the checkout.

You also have the option to add a formStyle to personalize your payment form. For more in-depth information, please go to Customized Form.

After the payment has been processed, a page displaying the transaction status is presented, and the customer is then redirected to the redirectUrl defined.

You can find the default look and feel of the Payment Form below, where the customers can seamlessly enter their payment details and complete the transaction:

Step 3: Get the payment status

You can check the status of your transaction making a GET request.

GET {transactionID}/status
Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
Request Headers:
Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>
Content-Type: application/json