SIBS PAYMENT GATEWAY - Getting Started
Form Integration is based on three simple steps:
Prepare the checkout
Create the payment form
Get the payment status
Server-to-Server Integration is based on the following steps:
Prepare the checkout
Display payment method option to customer
Create the transaction
Get the payment status
Webhooks are HTTP callbacks that notify you of all events you subscribed for an entity.
Form Integration
Form Integration enables merchants to integrate the SIBS Gateway through a secure Form avoiding a PCI-DSS Certification.
This the quickest and simplest way to integrate, allowing merchants to use 3 different payment methods (MB WAY, Credit Cards and MB Reference) using a single Form.
Besides this, Form integration offers three types of layouts to better suit the merchant needs.
Form Integration is based on three simple steps:
Prepare the Checkout
Firstly, perform a server-to-server POST request to prepare the checkout with the required data, where you should include the payment type, amount, currency and payment methods allowed.
The JSON of your POST body, can be composed of various Complex Types:
"merchant": {
"terminalId": {{terminalId}},
"channel": "web",
"merchantTransactionId": "gp9253eg4o"
}
For more info check SIBS API Market
"transaction": {
"transactionTimestamp": "Current Date",
"description": "My transaction -> Order Order Id: gp9253eg4o",
"moto": false,
"paymentType": "PURS",
"amount": {
"value": 5,
"currency": "EUR"
},
"paymentMethod": [
"REFERENCE",
"CARD",
"MBWAY"
],
"paymentReference": {
"initialDatetime": "Current Date",
"finalDatetime": "Expiration Date",
"maxAmount": {
"value": 5,
"currency": "EUR"
},
"minAmount": {
"value": 5,
"currency": "EUR"
},
"entity": "24000"
}
}
For more info check SIBS API Market
"customer": {
"customerInfo": {
"customerEmail": "client.name@hostname.pt",
"shippingAddress": {
"street1": "Rua 123",
"street2": "porta 2",
"city": "Lisboa",
"postcode": "1200-999",
"country": "PT"
},
"billingAddress": {
"street1": "Rua 123",
"street2": "porta 2",
"city": "Lisboa",
"postcode": "1200-999",
"country": "PT"
}
}
}
For more info check SIBS API Market
"recurringTransaction": {
"validityDate": "2022-09-28T17:37:31.4095147+00:00",
"amountQualifier": "DEFAULT",
"description" : "My transaction -> Order XPTO"
}
For more info check SIBS API Market
"tokenisation":{
"tokenisationRequest":{
"tokeniseCard":true
}
}
For more info check SIBS API Market
The response to a successful request is a JSON with a transactionID, which is required on the second step to create the payment form.
With the transactionID, will be present as well a formContext that will be used on the following step
POST https://spg.qly.site1.sibs.pt/api/v1/payments
/api/v1/payments
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:
<script src="/assets/js/widget.js?id={transactionID}"></script>
{formContext}
that you get as response from the first step, a {formConfig}
and optionally
{formStyle}
<form class="paymentSPG" spg-context="{formContext}" spg-config="{formConfig}" spg-style="{formStyle}"><form>
Your transactionID , and formContext from step 1:
TransactionID :
{formConfig}
and optionally {formStyle}
are important to be able to create the from correctly. You can find an example of each below:
{ "paymentMethodList": [],
"amount": { "value": 5, "currency": "EUR" },
"language": "en",
"redirectUrl": "https://www.pay.sibs.com/documentacao/sibs-gateway",
"customerData": null }
{ "transaction": {
{
"layout": 'default',
"theme": 'default',
"color": {
"primary": "",
"secondary": "",
"border": "",
"surface": "",
"header": {
"text": "",
"background": ""
},
"body": {
"text": "",
"background": ""
}
},
"font": ""
}
Get the payment status
Once the payment has been processed, the customer is redirected to your redirectUrl (defined in "spg-config"
), you can check the status of your transaction making a GET request.
GET https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
/api/v1/payments/{transactionID}/status
Server-to-Server
Server to Server Integration enables direct communication between the merchant and SIBS.
Through this integration the cardholders can finalize the payment without being redirected to SIBS form.
In order to use Card payments with Server-To-Server integration method, it's mandatory being PCI-DSS Compliant, which allows merchants flexible workflows on frontend and backend processes.
Server-to-Server Integration is based on the following steps:
Create Checkout Server-to-Server
Firstly, perform a server-to-server POST request, as Form Integration, to prepare the checkout with the required data, where you should include the payment type, amount, currency and payment methods allowed.
The JSON of your POST body, can be composed of various Complex Types:
"merchant": {
"terminalId": {{terminalId}},
"channel": "web",
"merchantTransactionId": "{{mti}}"
}
For more info check SIBS API Market
"transaction": {
"transactionTimestamp": "Current Date",
"description": "My transaction -> Order XPTO",
"moto": false,
"paymentType": "PURS",
"amount": {
"value": 5,
"currency": "EUR"
},
"paymentMethod": [
"REFERENCE",
"CARD",
"MBWAY"
],
"paymentReference": {
"initialDatetime": "Current Date",
"finalDatetime": "Expiration Date",
"maxAmount": {
"value": 5,
"currency": "EUR"
},
"minAmount": {
"value": 5,
"currency": "EUR"
},
"entity": "24000"
}
}
For more info check SIBS API Market
"customer": {
"customerInfo": {
"customerEmail": "client.name@hostname.pt",
"shippingAddress": {
"street1": "Rua 123",
"street2": "",
"city": "Lisboa",
"postcode": "1200-999",
"country": "PT"
},
"billingAddress": {
"street1": "Rua 123",
"street2": "",
"city": "Lisboa",
"postcode": "1200-999",
"country": "PT"
}
}
}
For more info check SIBS API Market
"recurringTransaction": {
"validityDate": "2022-09-28T17:37:31.4095147+00:00",
"amountQualifier": "DEFAULT",
"description" : "My transaction -> Order XPTO"
}
For more info check SIBS API Market
"tokenisation":{
"tokenisationRequest":{
"tokeniseCard":true
}
}
For more info check SIBS API Market
The response to a successful request is a JSON with a transactionID, which is required on the second step to create a transaction.
With the transactionID, will be present as well a transactionSignature that will be used on the next step.
POST https://spg.qly.site1.sibs.pt/api/v1/payments
/api/v1/payments
Generate Transaction
Configuration on Server-To-Server
Note that all the following requests need an Authorization Header with the "transactionSignature" returned from checkout operation.
On these requests, the Bearer Token is replaced by the checkout response "transactionSignature".
Example:
Authorization: Digest {transactionSignature}
Multibanco
POST https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/service-reference/generate
Generate Multibanco Reference
/api/v1/payments/{transactionID}/service-reference/generate
Authorization: Digest {transactionSignature}
{}
MBWAY
Generate MBWAY Payment
Insert the phone number to use:
POST https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}}/mbway-id/purchase
/api/v1/payments/{transactionID}/mbway-id/purchase
Authorization: Digest {transactionSignature}
Get the payment status
Once the payment has been processed, you must redirect the client to a thank you page and present a message depending on the paymentStatus
. You can check the status of your transaction by making a GET request.
GET https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
/api/v1/payments/{transactionID}/status
BackOffice Operations
The BackOffice APIs allow merchants to perform different BackOffice operations over their transactions, for example a capture, refund, cancelation and recurring transaction.
Capture
A capture is used to request a debit to previously authorized transaction.
A capture request is performed using a previous payment authorization (AUTH) payment by referring its transactionID and sending a POST request over HTTPS to the /payments/{transactionID}/capture endpoint.
Captures can occur in different ways:
POST /api/v1/payments/{transactionID}/capture
/api/v1/payments/{transactionID}/capture
Cancelation
A cancelation is performed using a previous payment authorization (AUTH), by referring its transactionID and sending a POST request over HTTPS to the /payments/{transactionID}/cancelation endpoint.
When canceling a payment and, if sent within the time-frame, the authorization is not captured yet, instead it causes an authorization reversal request to be sent to the card issuer to clear the funds held against the authorization. If requested over a MULTIBANCO Reference generated but not paid, the reference will be cancelled.
POST /api/v1/payments/{transactionID}/cancelation
/api/v1/payments/{transactionID}/cancelation
Refund
The purpose of this operation is to refund the amount of a previous payment, crediting the cardholder account and debiting the Merchant account.
A refund can be:
It can be a full refund, when the total amount of the purchase is refunded to the cardholder, or a partial refund, when a subtotal of the purchase is refunded to the cardholder.
POST /api/v1/payments/{transactionID}/refund
/api/v1/payments/{transactionID}/refund
Recurring
The purpose of this operation is to allow the merchant to charge a recurrent service, in the first stage the cardholder requests the payment as an initial recurring and authorize the merchant to do future debits (following recurring) accordingly with the service
Webhooks
A webhook is an API that provides with real-time information. SIBS uses webhooks to inform the merchants regarding changes to a transaction payment status.
The Merchant can receive the notifications either by email or endpoint (notification assembling to the status inquiry – Checkout Status), however only a notification will be sent for each transaction.
Notifications sent straight to the endpoint (URL) configured by the Merchant. The parameterization of this endpoint needs to be done on the SIBS BackOffice.
Each time that SIBS Gateway receives an update on the payment status of a transaction, a notification will be sent with the new transaction paymentStatus
.
Every day SIBS Gateway sends a summarized email with the newest failed notifications (email needs to be registered on the BackOffice).
There is no guarantee on the order of messages, especially if the time difference between the notifications is smaller than the time it takes to process them or by any communication or systems issues. Once the issues are sort out, new notifications will arrive in real time and old notifications will be resent. In case that no notification is received, the option “Checkout Status” should be used before rejecting any transaction.
Notifications are sent as HTTPS callbacks (webhooks) to an endpoint on your server. Please ensure you have a valid SSL certificate chain. Self-signed certificates are not valid.
To receive notifications, you need a server that has:
Depending on your network and security requirements, you might also need to add our network to your firewall's whitelist.
To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with an HTTP 200 and a response containing:
{
"statusCode": "200",
"statusMsg": "Success",
"notificationID": "2533e456-5e36-42c8-9eea-7961902f185e"
}
When your server receives a notification it should:
{ "statusCode": "200", "statusMsg": "Success","notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" }
Decrypt
The content of notification is encrypted to protect data from fraud attempts. When converting human-readable string to hexadecimal format, we use UTF-8.
Format of body: Base64 Format of Initialization Vector: Base64
Secret:
|
O0Bur9uhZkS54NkwFhVyeutED6DhLbOQUBDt3i3W/C4= |
X-Authentication-Tag:
|
Ytw9bzOS1pXqizAKMGXVQ== |
Content-Type:
|
text/plain |
X-Initialization-Vector:
|
Ldo3OyWNgRchSF3C |
Body before decryption:
|
WgErmJOV6wg3BuRkrgZLUUnh57BYzhIzvBFdpadHRsc43UcjtZEevRGDIDu3YxocXMXe8O+xQpMRxwTJPv766IaNqUiUEjAIj ZSMEYCZ0pBursUYB+9nB4eqNUiAS2MJ9sR+Cj2iBf6G6KXLfp9K6dK7c0UED5XrJwbovY8X8pMyxktFTEaflp0e76ZywsCQvt qEtqNz9uYEyqmAANbsBwbwyWpkCC8H1kZN2fV3CYetW1CTPmWdPp3C18Yfh826NN4XlKu1VmUmea70PyjmRKSsjPXpfrRX8ud elVIK2WTFtnRxD4x588d1nlGY5D5DQmJ8KYZzfvjTmDXGAPiRIEGuXp8h6rBQXS8P/m1llBtboGgQv4MmW3zvq0G6KFlYIcM= |
Body after decryption:
|
{ "returnStatus": { "statusMsg": "Success", "statusCode": "000" }, "paymentStatus": "Success", "paymentMethod": "CARD", "transactionID": "WebhookTest", "amount": { "currency": "EUR", "value": 10.0 }, "merchant": { "terminalId": 1000000 }, "paymentType": "PURS", "notificationID": "f153c248-e7be-4c12-8d88-6c9f1f3b83e4" } |
Examples
Below you can find some examples of how to decrypt the webhook notification:
|
|
|
|
API Reference
For more info check SIBS API Market
Credentials
How to get your credentials ?
Below you will be able to configure which credentials you will use on the examples above.
You can use the default one or change them to your Test Credentials, provided by onboarding@sibs.pt
TerminalId
|
Provided by Onboarding on your credential kit |
X-IBM-Client-Id
|
Provided by Onboarding on your credential kit |
Bearer / Access Token
|
Provided by Onboarding on your credential kit |
Payment type
|
For one time transactions - PURS For two time transactions - AUTH |
Payment Entity
|
Provided by Onboarding on your credential kit |
Payment Method
|
Selected when you sign the contract with the Bank |
TerminalId
|
Obtained on SIBS BackOffice, or provided by your bank |
X-IBM-Client-Id
|
Obtained on SIBS BackOffice, or provided Onboarding |
Bearer / Access Token
|
Obtained on SIBS BackOffice |
Payment type
|
For one time transactions - PURS For two time transactions - AUTH |
Payment Entity
|
Obtained on SIBS BackOffice, or provided by your bank |
Payment Method
|
Selected when you sign the contract with the Bank |