Getting Started
Our payment solution will enable you to accept online payments with the most used methods, simplify your checkout process and boost your sales.
Form Integration
Form Integration is based on three simple steps:
Server-to-Server Integration
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
BackOffice APIs
There are also provided BackOffice APIs to perform a:
Webhooks
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: sends payment data, including payment method data.
- Create the payment form: displays a Payment Form to allow customers to submit payment method data.
- Get the payment status: gets the payment status.
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:
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://api.qly.sibspayments.com/sibs/spg/v2/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:
- The checkout’s transactionID that you got as response from first step:
<script src="https://spg.qly.site1.sibs.pt/assets/js/widget.js?id={transactionID}"></script>
- The
{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>
- The
{formConfig}
and optionally{formStyle}
are important to be able to create the from correctly. You can find an example of each below:
Create 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://api.qly.sibspayments.com/sibs/spg/v2/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:
- 1. Prepare the checkout: sends payment data, including payment method data.
- 2. Display payment method options to customer: displays payment method option to customer.
- 3. Update payment method data: sends payment method and its required data.
- 4. Get the payment status: gets the payment status.
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:
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://api.qly.sibspayments.com/sibs/spg/v2/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://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/service-reference/generate
Request URL:
/api/v1/payments/{transactionID}/service-reference/generate
Authorization: Digest {transactionSignature}
{}
MBWAY
POST https://api.qly.sibspayments.com/sibs/spg/v2/payments/{transactionID}/mbway-id/purchase
Phone Number:
Request URL:
/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://api.qly.sibspayments.com/sibs/spg/v2/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:
- Full, capture the full amount authorized and finish the purchase.
- Partial, split the capture over one or several capture requests, up to the total amount authorized.
POST https://spg.qly.site1.sibs.pt/api/v1/payments/{transactionID}/capture
/api/v1/payments/{transactionID}/capture
Cancellation
A cancellation 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 cancelling 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 https://spg.qly.site1.sibs.pt/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:
- Performed against a previous payment, referring its transactionID by sending a POST request over HTTPS to the /payments/{transactionID}/refund endpoint.
- Performed against a purchase (PURS) or captured preauthorization (AUTH -> Capture) payment types.
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 https://spg.qly.site1.sibs.pt/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
- Initial Recurring – Required to register as initial recurring
- Following Recurring – Triggers following payments
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:
- An endpoint that can receive an HTTP POST.
- An open TCP port for HTTPS traffic (443, 80) with TLSv1.2.
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:
- Decrypt the notification
- Store the notification in your database
- Acknowledge the notification with an HTTP 200 OK and the following response body:
{ "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.
- Encryption algorithm : AES
- Block mode : GCM
- Padding : None
- Initialization Vector : In HTTP header (X-Initialization-Vector)
- Authentication Tag : In HTTP header (X-Authentication-Tag)
Format of body: Base64 Format of Initialization Vector: Base64
Examples
Below you can find some examples of how to decrypt the webhook notification:
using System;
using System.Security.Cryptography;
using System.Text;
public static class Program {
public static void Main() {
byte[] secret = System.Convert.FromBase64String("6fNDiYU0T0/evFpmfycNai/AqF24i+rT0OmuVw0/sGQ=");
byte[] ciphertext = System.Convert.FromBase64String("9bIjURJIcwoKvQr+ifOTH3HbMX+IqmsRqHuG/I1GfbSX89JE5DcWh/p8QROC5pRAuYZ7"+"ln7RSkHXJdZpVz1LFQ2859WsetvHHui7qYmfxATOO1j0AQuPdAD3FeRH0kR4s/v3c2nV8"+"1DnUXFCnQER/+VWrYdbu5vn8gm+diSE6CHvkK+ODy0ebVi5O6VBnWVjgBUG33VwWiAyIl"+"7Ik435V55WnZgynH3GfbVYoGwZ5UhYtn3yw2yruiLAKu6VTBvnh/ZJP21cHCJSF6NPSd+8"+"1gzWFU/+ECm3cf3uBbCkmKmL7HxRhRxhG0lMtX6ELZOXuw3eDJ1BTu+sSMkV/5Xk+5XX48"+"XmP6CGZ7KmP7Q3Fw1kZmhn0unFyv0Gw8PjT1Ohny/HMgNl16I=");
byte[] nonce = System.Convert.FromBase64String("RYjpCMtUmK54T6Lk");
byte[] tag = System.Convert.FromBase64String("FUajWHmZjP4A5qaa1G0kxw==");
using (var aes = new AesGcm(secret))
{
var plaintextBytes = new byte[ciphertext.Length];
aes.Decrypt(nonce, ciphertext, tag, plaintextBytes);
string decrypt = Encoding.UTF8.GetString(plaintextBytes);
Console.WriteLine(decrypt);
}
}
}
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