Checkout / Get Status 

Checkout API includes two operations:

Checkout Payment

POST <ROOT_URL>/api/v2/payments

Checkout Status

GET <ROOT_URL>/api/v2/payments/{id}/status

For more information about APIs please follow the link below:

https://developer.sibsapimarket.com/sibs-qly/apimarket/product

Front office

SIBS Gateway form integration.

Widget Endpoint: The <ROOT_URL> will depend on the environment where we are working. 

To be a valid Merchant on SIBS Gateway it will be necessary to have an authorisation token (<AuthToken>), <terminalId>.

Request API

POST <ROOT_URL>/api/v2/payments

SIBS Gateway Form Integration 

Request header

Authorisation: ‘Bearer* <AuthToken>’ 
X-IBM-Client-Id: ’<clientid**>’ 
Content-Type: ‘application/json’ 

Table notes

* If “Bearer” is part of a header, then it will not have limitations in terms of field size. If the field isn’t part of a header, the size must be maximum 1024 Text. 

** If “clientId” is part of a header, then it will not have limitations in terms of field size. If the field isn’t part of a header, the size must be maximum 36 Text. 

Table info

(1) Merchant: parameterisation defined by the agreement between SIBS and the Merchant; 

(2) Transaction: parameterization related to the transaction, “moto” is in the case of being a transition “Mail Order Telephone Order”. The paymentType is ‘AUTH’ or ‘PURS’; 

(3) MerchantInitiatedTransaction: optional parameterization to create a transaction with Initial Cardholder Initiated Transaction; 

(4) Tokenization: optional parameterization to create a transaction with Tokenization; 

(5) Mandate: In Authorised Payment creation, mandateId is not present and mandateType must indicate type (“ONECLICK” or “SUBSCRIPTION”). In this case MandateCreationOnly can also be present. When MandateCreationOnly is present, “True” indicates “Only Creates Authorised Payment”, and “False” indicates “Creates Authorised Payment and requests payment”; 

When Client requests a payment using an Authorised Payment previously created, mandateId must be filled in with the Authorised Payment Identification. In this case merchantType and MandateCreationOnly are not present. 

Response (with success)

Table info

(5) transactionID: SIBS ID of transaction is used as the identifier of the transaction on the next APIs (<transactionID>).

(6) paymentMethodList: Payment methods available for the Merchant.

(7) formContext: Parameter to pass when building the SPG-form (Widget & Construction of SPG-form).

(8) mandate: mandateAvailable is set to ‘True’ if current Client has an active Authorised Payment for current Merchant and it is ready to be used. Attribute termsAndConditions indicates Merchant URI with Authorized Payment Terms & Conditions. 

Widget construction

After a successfully request checkout, we can display the SPG-FORM, by adding a form with the class ‘paymentSPG’, and run “ROOT_URL/assets/js/widget.js?id=<transactionID>” script (Note that ROOT_URL is root URL depending on the environment). For the Merchant to have access to the SPG-FORM it is necessary to insert a form with the payment class in the DOM of Merchant HTML page with the following attributes: 

• attr.spg-context: formContext (7) received from Checkout.
• attr.spg-config: configurations defined by the merchant (spg-config). 

This form has three input attributes: attr.spg-context, attr.sog-config, and attr.spg-style.

The attribute attr.spg-context should be the formContext from the Successful checkout response.

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

SIBS Gateway configurations

spg-style – Merchant Configurations : The attribute attr.spg-style is a JSON string, optional allowing the Merchant to customize the SPG-FORM: 

SIBS Gateway style

{
 layout?: 'default' | 'accordion' | 'list';
  theme?: 'default' | 'light' | 'dark' | 'grey';
 color?: {
  primary?: string,
 secondary?: string,
  border?: string,
 surface?: string,
 header?:{
 text?: string,
 background?: string
 }
 body?: {
  text?: string,
 background?: string
 }
 },
 font?: string
}

Transaction Status Inquiry 

When the checkout is finished, the Merchant will be redirected to a URL (or to the root of his own website), and, to check the transaction status, they need to do a new request to the API (Transaction Status Inquiry). 

API

GET <ROOT_URL>/api/v2/payments/<transactionID(5)>/status 

Request header

Authorisation: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ’<clientid>’ 

Body

(8) paymentStatus: payment status of the transaction;  

(9) token: In case a token was requested, card token generated; 

(10) paymentReference: In case a payment with reference (MULTIBANCO) has been requested, generated reference. 

Server to Server intregration

MULTIBANCO – MULITBANCO Service Reference 

MULTIBANCO Service Reference

API

POST <ROOT_URL>/api/v2/payments/{id}/service-reference/generate 

API

[POST] <ROOT_URL>/api/v2/payments/< originalTransactionID (5)>/service-reference/generate 

Request

Authorisation: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ’<clientid>’ 
HMAC: ‘String (Maximum 128 Base64 Text)’ (Optional) 

Response (with sucess)

Body

Complex types

Merchant

ReturnStatus

PaymentReference

ActionProcessed

ActionResponse

PaymentModalities

Backoffice

Cancellation API

POST <ROOT_URL>/api/v2/payments/{original-tx-id}/cancellation

When a success transaction happens from an authorisation, it is possible to execute a cancellation. 

API

[POST] <ROOT_URL>/api/v2/payments/< originalTransactionID (5)>/cancellation 

Request Header

Authorisation: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ’<clientid>’ 
Content-Type: ‘application/json’ 

Body answer

Response (with success)

Body answer

Refund API

POST <ROOT_URL>/api/v2/payments/{original-tx-id}/refund

When a success transaction happens from a capture or purchase, it is possible to execute a refund. 

API

[POST] <ROOT_URL>/api/v2/payments/< originalTransactionID (5)>/refund 

Request header

Authorisation: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ’<clientid>’ 
Content-Type: ‘application/json’ 
HMAC: string ‘Maximum 128 Base64 Text’ (Optional)

Body answer

Response (with success)

Body answer