Payment Gateway International

A webhook is an API that delivers real-time information regarding changes in the payment status of transactions.

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.

Merchants can receive notifications either by email or through an endpoint (notification assembled for the status inquiry – Checkout Status). However, only one notification will be sent for each transaction.

Notifications are sent directly to the endpoint (URL) configured by the merchant. The parameterization of this endpoint needs to be done in the SIBS Backoffice.

Each time the SIBS Gateway receives an update on the payment status of a transaction, a notification will be sent with the new transaction paymentStatus.

Every day, the SIBS Gateway sends a summarized email with the latest failed notifications (the email needs to be registered in the SIBS 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 due to any communication or systems issues. Once the issues are resolved, new notifications will arrive in real time, and old notifications will be resent. If no notification is received, the “Checkout Status” option should be used before rejecting any transaction.

Notifications are sent as HTTPS callbacks (webhooks) to an endpoint on your server. Please ensure that you have a valid SSL certificate chain. Self-signed certificates are not valid.

How it works?

To receive notifications, you need a server that has the following:

• An endpoint capable of receiving HTTP POST requests.
• An open TCP port for HTTPS traffic (port 443 or 80) with TLSv1.2 encryption.

Depending on your network and security requirements, you may also need to whitelist our network on your firewall. To ensure that your server correctly handles notifications, we require you to acknowledge every type of notification with an HTTP 200 and a response that includes:

{
 "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 as explained before.

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

Test notification example:

Secret: O0Bur9uhZkS54NkwFhVyeutED6DhLbOQUBDt3i3W/C4=
X-Authentication-Tag: Ytw9bzOS1pXqizAKMGXVQ==
Content-Type: text/plain
X-Initialization-Vector: Ldo3OyWNgRchSF3C

Body before decryption:

WgErmJOV6wg3BuRkrgZLUUnh57BYzhIzvBFdpadHRsc43UcjtZEevRGDIDu3YxocXMXe8O+xQpMRxwTJPv766IaNqUiUEjAIjZSMEYCZ0pBursUYB+9nB4eqNUiAS2MJ9sR+Cj2iBf6G6KXLfp9K6dK7c0UED5XrJwbovY8X8pMyxktFTEaflp0e76ZywsCQvtqEtqNz9uYEyqmAANbsBwbwyWpkCC8H1kZN2fV3CYetW1CTPmWdPp3C18Yfh826NN4XlKu1VmUmea70PyjmRKSsjPXpfrRX8udelVIK2WTFtnRxD4x588d1nlGY5D5DQmJ8KYZzfvjTmDXGAPiRIEGuXp8h6rBQXS8P/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 will find some examples demonstrating 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);


 }
 }
}

import java.security.Security;
import java.util.Base64;import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;import com.google.common.base.Charsets;import org.apache.commons.lang3.ArrayUtils;
import org.bouncycastle.jce.provider.BouncyCastleProvider;// For Java and JVM-based languages, you might need to install unrestricted policy file for JVM,
// which is provided by Sun. Please refer BouncyCastle FAQ if you get
// java.lang.SecurityException: Unsupported keysize or algorithm parameters or
// java.security.InvalidKeyException: Illegal key size.

// If you cannot install unrestricted policy file for JVM because of some reason, you can try with reflection: See here.public class Test {public static void main(String[] args) {try {
 Security.addProvider(new BouncyCastleProvider());// Data from configurationString keyFromConfiguration = "6fNDiYU0T0/evFpmfycNai/AqF24i+rT0OmuVw0/sGQ=";// Data from serverString ivFromHttpHeader = "RYjpCMtUmK54T6Lk";String authTagFromHttpHeader = "FUajWHmZjP4A5qaa1G0kxw==";String httpBody = "9bIjURJIcwoKvQr+ifOTH3HbMX+IqmsRqHuG/I1GfbSX89JE5DcWh/p8QROC5pRAuYZ7"
+"ln7RSkHXJdZpVz1LFQ2859WsetvHHui7qYmfxATOO1j0AQuPdAD3FeRH0kR4s/v3c2nV8"
+"1DnUXFCnQER/+VWrYdbu5vn8gm+diSE6CHvkK+ODy0ebVi5O6VBnWVjgBUG33VwWiAyIl"
+"7Ik435V55WnZgynH3GfbVYoGwZ5UhYtn3yw2yruiLAKu6VTBvnh/ZJP21cHCJSF6NPSd+8"
+"1gzWFU/+ECm3cf3uBbCkmKmL7HxRhRxhG0lMtX6ELZOXuw3eDJ1BTu+sSMkV/5Xk+5XX48"
+"XmP6CGZ7KmP7Q3Fw1kZmhn0unFyv0Gw8PjT1Ohny/HMgNl16I=";// Convert data to processbyte[] key = Base64.getDecoder().decode(keyFromConfiguration);byte[] iv = Base64.getDecoder().decode(ivFromHttpHeader);byte[] authTag = Base64.getDecoder().decode(authTagFromHttpHeader);byte[] encryptedText = Base64.getDecoder().decode(httpBody);// Unlike other programming language, We have to append auth tag at the end of
 // encrypted text in Javabyte[] cipherText = ArrayUtils.addAll(encryptedText, authTag);// Prepare decryptionSecretKeySpec keySpec = new SecretKeySpec(key, 0, 32, "AES");Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
 cipher.init(Cipher.DECRYPT_MODE, keySpec, new IvParameterSpec(iv));
// Decryptbyte[] bytes = cipher.doFinal(cipherText);
 System.out.println(new String(bytes, Charsets.UTF_8));

 } catch (Exception e) {
 e.printStackTrace();
 }
 }
}

function sodium_decrypt( $webhookSecret, $iv_from_http_header, $http_body , $auth_tag_from_http_header ){$key = mb_convert_encoding($webhookSecret, "UTF-8", "BASE64");$iv = mb_convert_encoding($iv_from_http_header, "UTF-8", "BASE64");$cipher_text = mb_convert_encoding($http_body, "UTF-8", "BASE64") . mb_convert_encoding($auth_tag_from_http_header, "UTF-8", "BASE64");$result = sodium_crypto_aead_aes256gcm_decrypt($cipher_text, "", $iv, $key);return $result;

}$webhookSecret = "6fNDiYU0T0/evFpmfycNai/AqF24i+rT0OmuVw0/sGQ=";
$iv_from_http_header = "RYjpCMtUmK54T6Lk";
$auth_tag_from_http_header = "FUajWHmZjP4A5qaa1G0kxw==";
$http_body = "9bIjURJIcwoKvQr+ifOTH3HbMX+IqmsRqHuG/I1GfbSX89JE5DcWh/p8QROC5pRAuYZ7" .
"ln7RSkHXJdZpVz1LFQ2859WsetvHHui7qYmfxATOO1j0AQuPdAD3FeRH0kR4s/v3c2nV8" .
"1DnUXFCnQER/+VWrYdbu5vn8gm+diSE6CHvkK+ODy0ebVi5O6VBnWVjgBUG33VwWiAyIl" .
"7Ik435V55WnZgynH3GfbVYoGwZ5UhYtn3yw2yruiLAKu6VTBvnh/ZJP21cHCJSF6NPSd+8" .
"1gzWFU/+ECm3cf3uBbCkmKmL7HxRhRxhG0lMtX6ELZOXuw3eDJ1BTu+sSMkV/5Xk+5XX48" .
"XmP6CGZ7KmP7Q3Fw1kZmhn0unFyv0Gw8PjT1Ohny/HMgNl16I=";// Decrypt message
$result = sodium_decrypt($webhookSecret, $iv_from_http_header, $http_body , $auth_tag_from_http_header);print($result);

import base64
from Cryptodome.Cipher import AESdef decrypt_AES_GCM(encryptedMsg, authTag, secretKey, iv):
 iv = base64.b64decode(iv)
 encryptedMsg = base64.b64decode(encryptedMsg)
 secretKey = base64.b64decode(secretKey)
 authTag = base64.b64decode(authTag)
 aesCipher = AES.new(secretKey, AES.MODE_GCM, iv)
 plaintext = aesCipher.decrypt_and_verify(encryptedMsg, authTag)return plaintext

 example = {"encoded" : "9bIjURJIcwoKvQr+ifOTH3HbMX+IqmsRqHuG/I1GfbSX89JE5DcWh/p8QROC5pRAuYZ7" \
"ln7RSkHXJdZpVz1LFQ2859WsetvHHui7qYmfxATOO1j0AQuPdAD3FeRH0kR4s/v3c2nV8" \
"1DnUXFCnQER/+VWrYdbu5vn8gm+diSE6CHvkK+ODy0ebVi5O6VBnWVjgBUG33VwWiAyIl" \
"7Ik435V55WnZgynH3GfbVYoGwZ5UhYtn3yw2yruiLAKu6VTBvnh/ZJP21cHCJSF6NPSd+8" \
"1gzWFU/+ECm3cf3uBbCkmKmL7HxRhRxhG0lMtX6ELZOXuw3eDJ1BTu+sSMkV/5Xk+5XX48"
"XmP6CGZ7KmP7Q3Fw1kZmhn0unFyv0Gw8PjT1Ohny/HMgNl16I=","iv" : "RYjpCMtUmK54T6Lk","tag" : "FUajWHmZjP4A5qaa1G0kxw==","secret" : "6fNDiYU0T0/evFpmfycNai/AqF24i+rT0OmuVw0/sGQ="}


result = decrypt_AES_GCM(example['encoded'], example['tag'], example['secret'], example['iv'])
print(result)

In this section, we’ll delve into the webhook API operations, encompassing the processes of webhook creation, webhook list retrieval, and webhook updates, covering various aspects such as the operation method, endpoint, and request details.

Create webhook

In this segment we will explore the process of creating webhooks, outlining the necessary steps, parameters, and authentication details. 

Endpoints:

The following table presents the details required for initiating a Create Webhook operation:

Header parameters:

Request parameters:

Here, you can review the response structure resulting from the Create Webhook operation:

Get webhook list

In this section, we provide the details on the Get Webhook List operation, encompassing the operation method, endpoint, and necessary elements to retrieve a list of webhooks, with both the API request and response structures for your reference.

The table below outlines the required data elements and their conditions for initiating the request.

Header parameters:

Request parameters:

This table outlines the expected response elements:

Update webhooks

Here we address the operation method, endpoint, and relevant elements required for modifying a webhook resource. This includes a coverage of the API request and response structures for your reference.

The following table presents the essential elements for initiating an Update Webhook request:

Header parameters:

Request parameters:

This table outlines the response components for the Update Webhook operation:

Use SIBS Backoffice to establish webhooks and stay updated regarding your payments. Follow the subsequent steps and choose the appropriate options that correspond to your desired updates.

To take advantage of this feature, you can easily set up webhooks to receive notifications for events within your account. This will enable you to stay informed and take appropriate actions when necessary.

In the “Webhooks” menu, you can view a list of all your webhooks. You can quickly apply filters by credential, notifications, type, and webhook (email or URL).

When you click on the Webhook icon, two options may be presented depending on the type of webhook. If the webhook is a URL type, you can access its details and test it. If the webhook is an email type, you can only view its details in more depth.

Add a new Webhook

Step 1: Choose Webhook type (Mandatory)

Step 2: Add an URL (Mandatory)

Step 3: Webhook application choice (Mandatory)

Step 4: Choose notification types (Mandatory)

Step 5: Webhook secret (Mandatory)

Step 6: Webhook email for support

To create a new webhook, you need to click on the “Add new webhook” button. Then, a set of steps will be presented to guide you in filling in the necessary data to create a webhook. The following images show an example of creating a URL-type webhook.

Step 1: Choose Webhook type (Mandatory)

When it comes to delivering notifications, a webhook for URL sends real-time data by making an HTTP request to a specified endpoint, whereas a webhook for email delivers the notifications by sending them as email messages to a designated email address.

Step 2: Add an URL (Mandatory)

Step 3: Webhook application choice (Mandatory)

Webhooks can be defined for the merchant, store, or terminal. If they are defined for the merchant, they will apply to all stores and terminals contained within it.

Defining webhooks for a store only applies to the terminals within that store.

If you want to define a webhook for a specific terminal, you should choose that option.

Step 4: Choose notification types (Mandatory)

Step 5: Webhook secret (Mandatory)

Step 6: Webhook email for support

Once all the required data has been filled in, you can click on the “Create webhook” button to create the webhook.

Webhook delete

If you have the permission to manage webhooks, you can delete notifications that are no longer needed. To do this, you must click on the “Delete” option located in the top right corner of the Webhook details page. Once you click on it, an operation confirmation popup will be displayed, and you can delete the Webhook.

Webhook test

You can easily test a webhook as long as it is of type URL. To do this, simply click on the “Test” button and you will be directed to the webhook testing page. Once there, click the test button and wait for the request to complete successfully. The notification sent will then be displayed, confirming that the webhook is working correctly.

Webhook details

To view all the details of a webhook, you need to click on the “Details” option. This will provide you with a more detailed view of the webhook data. If you need to make any changes, simply click on the pencil icon to edit the information. Once you have updated the data, click on the save icon to ensure that the new information is saved.

Take advantage of these resources to help you test your integration across various scenarios.

Testing Credentials

Consult your Account Manager to initiate the onboarding process.

Once this process is finished, you will receive your testing credentials, including:

• Terminal Code
• Bearer Token
• Client ID

When you have your credentials, you are ready to start the integration process.

Within your testing environment, you gain the ability to:

• Digitally onboard your merchants, in case you are a Payment Facilitator
• Initiate your integration process
• Explore the features and tools at your disposal
• Conduct test payments

Keep in mind that a test account allows you to explore SIBS integrations but does not guarantee live payment processing.

Testing Cards

Prior to implementing live payment processing, you have the option to use the provided card details from this page for testing purposes. 

Please note that these details are exclusively applicable on our testing platform and do not involve actual transactions or the transfer of any funds.

Here are some testing cards you can use:

Handling responses

Response codes provide valuable insights into the outcome of an API request. This page provides a comprehensive description of the potential response codes you may encounter.

HTTP Status Codes

HTTP defines a set of forty standard status codes that communicate the results of a client’s request. These status codes are categorized into the following five groups:

Code references

Codes serve as crucial identifiers in various domains, including the realm of payments.

Below you can find the ISO Codes used for:

The API-based onboarding process eliminates the need for manual onboarding by automatically generating sponsored merchants, establishments, pricelists, terminals, and their corresponding credentials.

The Merchant’s NIP and backofficeEmail parameters in the POST request must each have unique values and should not be reused.
Attempting to reuse these values will results in an unsuccessful completion of the onboarding process.

Please check below the available environment endpoints:

To initiate this process, you are required to perform a POST request with the following data:

Header parameters:

Request parameters:

Find below a POST request example:

{
 "merchant": {
 "name": "JOHN DOE",
 "phone": "505102923",
 "email": "fds@op.pl",
 "nip": "6831968575",
 "mcc": "5969",
 "pkd": "86.90.E",
 "merchantType": "Sponsored Merchant",
 "address": {
 "street": "UL IMAGINARY",
 "postalCode": "85-132",
 "locality": "BYDGOSZCZ",
 "country": "616"
 },
 "website": "www.yolo.pl",
 "signedAgreements": true,
 "backofficeEmail": "fds@op.pl",
  "pepStatus": "Inactive",
 "owners": [
 {
 "name": "JANE DOE",
 "phone": "505102923",
 "email": "fds@op.pl",
 "address": "UL UGORY 85-132 BYDGOSZCZ POLSKA",
 "tin": "6831968575"
 }
 ],
 "shop": {
 "name": "YOLO",
 "address": {
 "street": "UL IMAGINARY",
 "postalCode": "85-132",
 "locality": "BYDGOSZCZ",
 "country": "616"
 },
 "email": "fds@op.pl",
 "phoneNumber": "505102923",
 "type": "Retail",
 "mcc": "5969",
 "pkd": "86.90.E",
 "invoiceIndicator": "Payment Facilitator",
 "products": [
 {
  "productId": "INTP-BLIK-0-0",
 "productInvoiceIndicator": "Payment Facilitator"
 },
 {
 "productId": "KEVN-PYBL-0-0",
 "productInvoiceIndicator": "Payment Facilitator"
 }
 ],
 "paymentMethodType": "Bank Transfer",
 "invoiceEmail": "fds@op.pl",
 "payout": {
 "bankAccount": "50116022020000000127761999",
 "iban": "PL50116022020000000127761999",
 "bic": "BIGBPLPW",
 "numDaysPayout": 1.0
 },
 "typeOfIntegration": "S2S",
 "webhookNotification": {
 "type": "URL",
 "value": ""
 },
 "supportEmail": "",
 "securityKey": ""
 }
 }
}

Upon this action, the API will respond with one of the following two status codes:

Here is an example of a successful onboarding response:

{
"transactionStatus": "ACT",
 "returnStatus": {
 "statusCode": "000" "statusMsg": "Success",
 "statusDescription": "string"
 }
}

You will also receive the onboarding webhook, which includes the following merchant onboarding details and credentials.

Here’s a redacted example of a successful Webhook notification:

{
 "NotifyRequest": {
 "TrackingId": "00caa675-f811-45ed-aee3-b84c22ac3efc",
 "TIN": "000****123",
 "MerchantId": "PL-000****123-1",
 "ShopId": "SH-PL-000000321",
 "TerminalId": "POS000159",
 "ErrCode": "CRM000",
 "ErrDesc": "Success",
 "Agreements": {
 "AgreementType": "PLKV"
 },
 "Credentials": {
 "ApiClientId": "2a69a780-****-****-****-1c6308af85f0",
 "ApiClientSecret": "K1rK*******************************0uU6",
  "TerminalToken": "0277a2c645e93c43f59ce867ee55498293*******5272db028ad9c9fa250edd04d9cac5d42910950e2acb82034093d14830e649c3d6df2cc0f92268f79"
 }
 }
}

Please note the following essential credentials for your API Integrations:

 

Credentials.ApiClientId: The API Client ID needed for calling the Payment API, provided as the ‘x-ibm-client-id’HTTP header.

 

Credentials.ApiClientSecret: Currently not required for any Payment API, but it should be stored securely in case it’s needed in the future.

 

Credentials.TerminalToken: The OAuth Bearer Token to be used as the ‘Authorization:Bearer’ HTTP header for the Checkout API and Backoffice API.

Error handling

If a rejection occurs on the onboarding process, a synchronous response will be received that include a transactionstatus with the value RJCT (rejected) and a 999 StatusCode.

This response will contain error code and message fields that can assist you in identifying and resolving the issue.

Rejected onboarding response example:

{
"transactionStatus": "RJCT",
  "returnStatus": {
 "statusCode": "999",
 "statusMsg": "Internal Server Error",
 "statusDescription": "When invoiceIndicator is Sponsored Merchant invoiceEmail and payout object are mandatory."
 }
}

Webhooks Status Codes

Below you can find the range of Status Codes and Messages that you can receive via webhooks.

The table below shows the available {API Host}.

Please refer to the following structure of the endpoint for your reference.

You should replace the placeholder {API Host} with the desired environment you want to use.

Check out the latest updates for SIBS Gateway, starting from January 2023.