Checkout / Get status

Checkout API includes two operation: 

Checkout Payment:

POST <ROOT_URL>/api/v2/payments

Checkout Status:

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

Tokenization

Token API:

POST <ROOT_URL>/api/v2/payments/{id}/token/purchase

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 

Table – SIBS Gateway Form Integration 

Request header

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

Table notes

(1) Merchant: parameterization 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)

(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.

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-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 Integration

Get Payment Modalities

API that will allow, in the checkout, receiving data regarding card payment modalities. 

API

GET /sibs/spg/{version-id}/payment-modalities/{id}/list 

Request header

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

Path:

Id: <TransactionId>

Complex types

Merchant

ReturnStatus

PaymentReference

ActionProcessed

ActionResponse

Backoffice

Merchant Initiated Transaction API

Merchant Initiated Transaction API

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

When a successful transaction is generated as Initial Transaction (3), the Merchant will be able to perform Merchant Initiated Transaction payments. 

The Merchant Initiated Transaction API provides a way for Merchants to request recurring transactions.

APIs

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

Request

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

Request Header

Response (with success)

Capture API 

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

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

API

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

Request

Authorisation: 'Bearer <AuthToken>'
X-IBM-Client-Id:'<clientid>'
Content-Type: 'application/json'
HMAC: 'String (Maximum 128 Base64 Text)' (optional)

Request header

Response (with success)

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