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
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.
ROOT_URL QLY
https://api-qly.sibspayments.com
ROOT_URL PRD
https://api.sibspayments.comRequest API
[POST] <ROOT_URL>/api/v2/paymentsSIBS Gateway Form Integration
Request header
Authorisation: ‘Bearer* <AuthToken>’
X-IBM-Client-Id: ’<clientid**>’
Content-Type: ‘application/json’ string (“AUTH”, “PURS”, “CAPT”, “CAUT”, “RFND”, “RCON”, “RVSL”, “STIQ”, “PREF”, “CPRF”, “CMBW”, “MAND”, “MAUT”, “MPUR”, “MITR”])
string ([“MBWAY”, “REFERENCE”, “CARD”, “TOKEN”, “STATIC”, “MANDATE”])
String
Value representing the browser language as defined in IETF BCP47
String
Required when Browser JavaScript Enable = True
Possible values:
([“1”, ”4”, “8”, “15”, “16”, “24”, “32”, “48”])
- 1 = 1 bit
- 4 = 4 bits
- 8 = 8 bits
- 15 = 15 bits
- 16 = 16 bits
- 24 = 24 bits
- 32 = 32 bits
- 48 = 48 bits
String (Maximum 6 Numeric Text)
Required when Browser JavaScript Enable = True
String (Maximum 6 Numeric Text)
Required when Browser JavaScript Enabled = true
String
Required when Browser JavaScript Enabled = true
Value is returned from the getTimezoneOffset() method
Examples:
If UTC -5 hours:
([“300”, “+300”])
If UTC +5 hours:
([“-300”])
string ([“ACTUAL”, “ESTIMATED”, “DEFAULT”])
If not present, the “DEFAULT” value is assumed.
If merchantInitiatedTransaction has MITType “UCOF”, the amountQualifier must be set to “ESTIMATED”.
(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)
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).
Note: this form has three input attributes: attr.spg-context, attr.spg-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:
| Parameters name | Type | Available values | Description |
|---|---|---|---|
| paymentMethodList | string | ‘MBWAY’, ‘REFERENCE’, ‘CARD’, ‘TOKEN’, ‘STATIC_QRCODE’, ‘MANDATE’ | Payment methods to show on the form. Payment methods for which the Merchant does not have permissions will not work. |
| redirectURL | String (Maximum 2048 Text) | – | URL to where the User should be redirected at the end of the checkout. |
| amount | {value: number, currency: string } | Value with format double Currency in ISO 4217 Alpha-3 Code. | Transaction amount value |
| language | string | ISO 3166 ‘pt’ ‘en’ | Form language |
| CustomerData | – | – | – |
- spg-style – Merchant Configurations
The attribute attr.spg-style is a JSON string, optional allowing the Merchant to customize the SPG-FORM:
| Parameter | Type | Possible values | Default | Description |
|---|---|---|---|---|
| LAYOUT | string | ‘default’, ‘accordion’, ‘list’ | ‘default’ | SPG Form Layout |
| THEME | string | ‘default’, ‘light’, ‘dark’, ‘grey’ | ‘default’ | SPG Form Theme |
| COLOR.PRIMARY | string | ‘#ff0000’ | – | Primary Color in Hexadeximal |
| COLOR.SECONDARY | string | ‘#ff0000’ | – | Secondary Color in Hexadeximal |
| COLOR.BORDER | string | ‘#ff0000’ | – | Border Color in Hexadeximal |
| COLOR.SURFACE | string | ‘#ff0000’ | – | Surface Color in Hexadeximal – surface is the ‘main background’ of the html page |
| COLOR.HEADER.TEXT | string | ‘#ff0000’ | – | Card Header Text Color in Hexadeximal |
| COLOR.HEADER.BACKGROUND | string | ‘#ff0000’ | – | Card Header Color in Hexadeximal |
| COLOR.BODY.TEXT | string | ‘#ff0000’ | – | Color in Hexadeximal of the Text in the Background |
| COLOR.BODY.BACKGROUND | string | ‘#ff0000’ | – | Background Color in Hexadeximal – background is the background of the payment cards |
| FONTE | string | ‘Times New Roman’ | – | Font family used |
{
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>’ Response (with success)
string ([“Success”, “Partial”, “Declined”, “InProcessing”, “Pending”, “Timeout”, “Error”])
string ([“MBWAY”,”REFERENCE”,”CARD”,”TOKEN”, “STATIC_QRCODE”, “MANDATE”])
string (Maximum 256 Text)
([“Success”, “Partial”, “Declined”, “InProcessing“, “Pending”, “Timeout”, “Error”])
(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}/listRequest header
Authorisation: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ’<clientid>’
Content-Type: ‘application/json’ Path – Id: <TransactionId>
Response (with success)
string (Maximum 256 Text)
([“Success”, “Partial”, “Declined”, “InProcessing”, “Pending”, “Timeout”, “Error”])
Merchant
ReturnStatus
PaymentReference
ActionProcessed
ActionResponse
Backoffice
Merchant initiated transaction API
POST <ROOT_URL>/api/v2/payments/{original-tx-id}/mitWhen 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.
API
[POST] <ROOT_URL>/api/v2/payments/< originalTransactionID (5)>/mit Request header
Authorisation: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ’<clientid>’
Content-Type: ‘application/json’
HMAC: string ‘Maximum 128 Base64 Text’ (Optional) Original transaction id (Cardholder Initiated Transaction) to do future Merchant Initiated Transaction payments.
Response (with success)
Capture API
POST <ROOT_URL>/api/v2/payments/{original-tx-id}/captureWhen 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 header
Authorisation: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ’<clientid>’
Content-Type: ‘application/json’
HMAC: ‘String (Maximum 128 Base64 Text)’ (Optional) Body
Response (with success)
Cancellation API
POST <ROOT_URL>/api/v2/payments/{original-tx-id}/cancellationWhen a success transaction happens from an authorisation, it is possible to execute a cancellation.
API
[POST] <ROOT_URL>/api/v2/payments/< originalTransactionID (5)>/cancellation Authorisation: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ’<clientid>’
Content-Type: ‘application/json’
HMAC: string ‘Maximum 128 Base64 Text’ (Optional)Body answer
Response (with success)
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)