Payment Gateway Portugal

• The Merchant can receive notifications by email or endpoint (notification assembling to the status inquiry – Checkout Status), however, only a notification will be sent for each transaction.  
• Notifications are sent by endpoint straight to the URL provided by the Merchant. The parameterization of this endpoint needs to be done on the SIBS Gateway Backoffice.  
• For email notifications, only one notification will be sent per transaction.  
• For URL notifications not accomplished, retries will be attempted. Each time SIBS Gateway receives a transaction, a notification will be sent with the transaction status in real time. 
• 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 message order, 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 no notification is received, the option “Checkout Status” should be used before rejecting any transaction. 

Notification MULTIBANCO – Asynchronous: Make request – Need action – Get response 

Complex Types

MerchantNotificationRequest  

Body

MerchantNotificationResponse

Body

Error message

Multibanco

Transaction status

It is possible to receive the transaction statuses below: 

• IN PROCESSING – meaning that the transaction initiated is now in processing. 
• PARTIAL – it is pending to receive information. 
• SUCCESS – informing transaction OK, the transaction was executed with success. 
• DECLINED – indicating that the transaction was declined by an operation intervenient.  
• TIMEOUT – informing a potential communication error. 
• ERROR – indicating that the transaction was declined by external system. 

After the transaction is in processing, it will only retrieve the “partial” status if some action is pending to be taken. After that it will send the transaction status. 

Notifications (Merchant Notifications)

The Merchant can receive notifications by email or endpoint (notification assembling to the status inquiry – Checkout Status), however, only a notification will be sent for each transaction. Notifications are sent by endpoint straight to the URL provided by the Merchant. The parameterization of this endpoint needs to be done on the SIBS Gateway Backoffice. For email notifications, only one notification will be sent per transaction. For URL notifications not accomplished, retries will be attempted. Each time SIBS Gateway receives a transaction, a notification will be sent with the transaction status in real time.

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 message order, 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 no notification is received, the option “Checkout Status” should be used before rejecting any transaction.

There are two types of notifications, the Synchronous and the Asynchronous:

 

Asynchronous

• Make request – Need action – Get response → MULTIBANCO

Synchronous

• Make request – Get response.

Complex types

MerchantNotificationRequest

MerchantNotificationResponse

Examples

{ 
 "returnStatus": { 
 "statusMsg": "Success", 
 "statusCode": "000" 
 }, 

 "paymentStatus": "Success", 
 "paymentMethod": "MBWAY", 
 "transactionID": "DaBzrs8ayhQpi1EeenHe", 
 "transactionDateTime": "2022-11-12T16:18:53.127Z", 
 
 "amount": { 
 "currency": "EUR", 
 "value": 1.0 
 }, 
 
 "merchant": { 
 "terminalId": 49180 
 }, 

 "paymentType": "AUTH", 
 "notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" 
} 

Response examples

{ 
  "statusCode": "200", 
 "statusMsg": "Success", 
  "notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" 
} 

Request status QR Code example

{
 "returnStatus":{ 
 "statusMsg": "Success",
 "statusCode": "000" 
 },

 "paymentStatus": "Success", 
 "paymentMethod": "STATIC_QRCODE", 
 "transactionID": "3W005000159764", 
 "transactionDateTime": "2022-11-12T16:17:53.127Z",
 
  "amount":{ 
 "currency": "EUR",
 "value": 1.6 
 },

 "merchant": { 
 "terminalId": 46431
 }, 

 "paymentType": "PURS", 
 "financialOperation": {
 "product": { 
 "staticQRCodeId": "7ecf9d4e23334f7da6cb", 
 "twoStepPurchase": false, 
 "aliasName": "351#934885128", 
 "merchantContactType": "N.A",
 "productName": "Nome info", 
 "productQuantity": 1,
 "productAmount": 1.5, 
 "expeditionAmount": 0.1, 
 "contactClientIndicator": 1, 
 "customerSupportContact": "teste@info.com"
 },

 "billingInfo":{
 "billingTIN": "123456789",
 "billingAddressCity": "Lisboa ", 
 "billingAddressLine1": "Rua D João ", 
 "billingAddressLine2": "8 2drt", 
 "billingAddressPostalCode": "4646-846", 
 "billingMobilePhone": "+ 351 987654321"
 },

 "expeditionInfo": {
  "expeditionName": "Olga Rodrigues", 
 "expeditionAddressCity": "Lisboa ", 
 "expeditionAddressLine1": "Rua D João ", 
 "expeditionAddressLine2": "8 2drt", 
 "expeditionAddressPostalCode": "4646-846", 
 "expeditionMobilePhone": "+ 351 987654321"
 }
 },
 "notificationID": "5544b042-8b9a-451e-8421-53fcfe9538f8"
}

Create Authorised Payment creation example

{
 "returnStatus": {
 "statusMsg": "Success", 
 "statusCode": "000"
 },

 "paymentStatus": "Success",
 "paymentMethod": "MBWAY",
 "transactionID": "UpxBSsjySqaR80aEzWxa", 
 "transactionDateTime": "2022-11-11T16:18:53.127Z", 
 
 "amount": {
 "currency": "EUR",
 "value": 1.96 
 },

 "merchant": {
 "transactionId": "1009854",
 "terminalId": 45546
 },

 "paymentType": "AUTH", 
 "mbwayMandate": {
 "mandateIdentification": "12345690656800744652", 
 "mandateAction": "SSPN",
  "mandateActionStatus": "SCCS",
 "mandateType": "SBSC",
 "clientName": "Andresa COS", 
 "aliasMBWAY": "351#914341580"
 },

 "notificationID": "6e96b74f-ec33-4ca9-8cd3-1d00c5d82a0d"
}

Cardholder Initiated Transaction with Type Recurring example:

{
 "returnStatus": {
 "statusMsg": "Success",
 "statusCode": "000" 
 },

 "paymentStatus": "Success",
 "paymentMethod": "CARD",
 "transactionID": "s24nZiFtu15SCiW9vpDm", 
 "transactionDateTime": "2022-12-27T16:05:27.585Z", 

 "amount": {
 "currency": "EUR",
 "value": 11.2 
 },

 "merchant": {
 "transactionId": "6637262",
 "terminalId": 45546,
 "merchantName": "GOMERCIANTE DO LEGACY" 
 },

 "paymentType": "PURS",
 "notificationID": "a433453e-6e40-4f53-a80d-4985cffa36f6", 
 "merchantInitiatedTransaction": {
 "type": "RCRR",
 "validityDate": "2023-06-30T01:00:00+01:00", 
 "amountQualifier": "ACTUAL",
 
 "schedule": {
 "initialDate": "2022-12-27T00:00:00Z", 
 "finalDate": "2023-01-06T00:00:00Z", 
 "interval": "DAILY"
 } 
 }
}

Merchant Initiated Transaction with Type recurring example

{
 "returnStatus": {
 "statusMsg": "Success",
 "statusCode": "000" 
 },

 "paymentStatus": "Success",
 "paymentMethod": "CARD",
 "transactionID": "s2K9YuqPQuC9NkdCvDA4", 
 "transactionDateTime": "2023-01-06T00:00:03.378Z", 

 "amount": {
 "currency": "EUR",
  "value": 11.2 
 },

 "merchant": {
 "terminalId": 45546,
 "merchantName": "GOMERCIANTE DO LEGACY" 
 },

 "paymentType": "MITR",
 "notificationID": "3a9d8777-292d-48fb-971c-6e6558de0fd5", 
 "merchantInitiatedTransaction": {
 "type": "RCRR", 
 "amountQualifier": "ACTUAL"
 }
}

Cardholder Initiated Transaction with Type UCOF example

{ 
 "returnStatus": { 
  "statusMsg": "Success", 
 "statusCode": "000" 
}, 

 "paymentStatus": "Success", 
 "paymentMethod": "CARD", 
 "transactionID": "s24nZiFtu15SCiW9vpDm", 
 "transactionDateTime": "2022-12-27T16:05:27.585Z",
 
 "amount": { 
 "currency": "EUR", 
 "value": 11.2 
 }, 

 "merchant": { 
  "transactionId": "6637262", 
 "terminalId": 45546, 
 "merchantName": "COMERCIANTE DO LEGACY" 
 }, 

 "paymentType": "PURS", 
 "notificationID": "a433453e-6e40-4f53-a80d-4985cffa36f6", 

 "merchantInitiatedTransaction": { 
 "type": "RCRR", 
 "validityDate": "2023-06-30T01:00:00+01:00", 
  "amountQualifier": "ACTUAL", 
 "schedule": { 
 "initialDate": "2022-12-27T00:00:00Z", 
 "finalDate": "2023-01-06T00:00:00Z", 
 "interval": "DAILY" 
 } 
 } 
} 

Merchant Initiated Transaction with Type UCOF example

{ 
 "returnStatus": { 
 "statusMsg": "Success", 
 "statusCode": "000" 
 }, 

 "paymentStatus": "Success", 
 "paymentMethod": "CARD", 
 "transactionID": "s2nYaNUC3hFpqd0HGq4Z", 
 "transactionDateTime": "2022-12-23T10:48:39.153Z","amount": { 
 "currency": "EUR", 
 "value": 5.16 
 }, 

 "merchant": { 
 "transactionId": "6540474", 
 "terminalId": 45546, 
 "merchantName": "GOMERCIANTE DO LEGACY" 
 }, 

 "paymentType": "MITR", 
 "notificationID": "c9786e7e-dc2a-4611-8a31-4b8197f41138", 

 "merchantInitiatedTransaction": { 
 "type": "UCOF", 
 "amountQualifier": "ESTIMATED" 
 } 

} 

Response example

{ 
 "statusCode": "200", 
 "statusMsg": "Success", 
 "notificationID": "2533e456-5e36-42c8-9eea-7961902f185e" 
} 

Error message

Checkout request

Payment request

Transaction status inquiry

Backoffice

Multibanco

Transaction status inquiry

Backoffice

Card

Checkout / Get Status 

Checkout API includes two operations:

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. 

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

SIBS Gateway Form Integration 

Request header

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

Table notes

* If “Bearer” is part of a header, then it will not have limitations in terms of field size. If the field isn’t part of a header, the size must be maximum 1024 Text. 

** If “clientId” is part of a header, then it will not have limitations in terms of field size. If the field isn’t part of a header, the size must be maximum 36 Text. 

Table info

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

Table info

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

spg-config – The attribute attr.spg-config is a JSON in a string format with the follow parameters: 

SIBS Gateway configurations

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 intregration

MULTIBANCO – MULITBANCO Service Reference 

MULTIBANCO Service Reference

API

POST <ROOT_URL>/api/v2/payments/{id}/service-reference/generate 

API

[POST] <ROOT_URL>/api/v2/payments/< originalTransactionID (5)>/service-reference/generate 

Request

Authorisation: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ’<clientid>’ 
HMAC: ‘String (Maximum 128 Base64 Text)’ (Optional) 

Response (with sucess)

Body

Complex types

Merchant

ReturnStatus

PaymentReference

ActionProcessed

ActionResponse

PaymentModalities

Backoffice

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

SIBS Gateway provides a collection of APIs that enables our Clients to process and manage payments. 

Our APIs allow to generate MULTIBANCO references to perform payments in the Multibanco ATM network or in the home banking solutions from card issuers.  

It is not necessary to choose all the SIBS Gateway payment solutions, our Clients can choose which API to use.

Form integration

To be a valid Merchant on SIBS Gateway V02.00 it will be necessary to have an authorisation token <AuthToken>, <terminalId>. 

Simple form integration with javascript based widget, on four simple steps: 

Step 1: Server-to-server request

Step 2: Create the payment form

Step 3: Get the payment status

Step 4: Merchant notification

Prepare the checkout: sends payment data, except payment method data.

Step 1: Server-to-server request

First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. The response to a successful request is a JSON with a transactionID, which is required in the second step to create the payment form.

Step 2: Create the payment form

Displays a payment form to allow customers to submit payment method data. To create the payment form you just need to add the following lines of HTML/Javascript to your page and populate the following variables: 

1. The checkout transactionID that was returned in the response from step 1

Change the variable in accordance with the environment – QLY or PRD. 

<script src="https://{QLY/PRD}/assets/js/widget.js?id={transactionID}"></script>

2. The {formContext} that you get in response from step 2  

{formConfig}; 
{formStyle} (optionally); 
 
<form class="paymentSPG" spg-context="{formContext}" spg-config="{formConfig}" spg-style="{formStyle}"><form> 

Configures the Merchant redirectUrl, which is the page on your website where the customer should be redirected after the payment.

Optional parameter that allows the user to change the form style. 

Step 3: Get the payment status

Gets the checkout status.
Once the payment is processed, the customer is redirect to your redirectUrl.
You can check the status of your transaction making a GET request.

Step 4: Merchant notification

Receive payment status. 
SIBS Gateway will send the notification of the asynchronous payment status.

Server-to-server integration

The Server to Server integration is also known as direct integration as it enables communication between the two servers, SIBS and Merchant. Cardholders can finalise a payment without being redirected to the SIBS Gateway Form. This integration is suitable for Merchants that store the payment data before sending them to the SIBS Payment Gateway. 

Financial operations

For financial operations, Server-to-Server Integration is based on the following steps: 

Step 1: Prepare the checkout

Step 2: Display payment method options to customer

Step 3: Update payment method data

Step 4: Get the payment status

Step 5: Merchant Notification

Step 1: Prepare the checkout

Sends payment data, except payment method data. 

First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. The response to a successful request is a JSON with a transactionID, which is required in the second step. 

Step 2: Display payment method options to customer

The next step is to provide the payment method options and get payment data from the customer: 

• Card
• MULTIBANCO
• MB WAY ID
• Authorised payment

Step 3: Update payment method data: sends payment method and its required data. 

Perform a payment request, call SIBS Gateway API with the collected data accordingly with the method. 

Step 4: Get the payment status: gets the payment status. 

Step 5: Merchant Notification: Receive payment status.

SIBS Gateway will send the notification of the asynchronous payments to the merchant server. 

Payment Card Industry Data Security Standard is an information security standard for organizations that handle branded credit cards from the major card schemes. The standard was created to increase controls around Cardholder data and reduce card fraud. 

Merchants that want to process, store or transmit card data will need to be PCI compliant. With SIBS the Merchants have the choice to use the FORM that is already fully PCI compliant, with no need of any certification from the store. The “Server-to-Server” API integration variant requires the Merchant to collect the card data, which increases the PCI-compliance needs. 

The Council does not enforce compliance. Compliance is requested by individual payment brands or acquiring banks.

PCI 3-Step Process

For more details: https://www.pcisecuritystandards.org/ 

Card is a synchronous payment that allows the Client to pay to the Merchant through a banking card by inserting the Name, Card Number, Expiring date and CVV.

Front office operations

The SIBS Gateway supports two types of operations, purchases and authorisations, where the purchase triggers the payment immediately and the authorisation keeps the amount captive until a capture is performed. 

Purchase: This transaction allows a Cardholder to pay for a good or service via an electronic operation that debits his account and will credit the Acceptors banking account. Consists in an immediate debit in the Client account and it is an effective payment on the moment of the transaction. 

Authorisation: Consists in an authorisation for a future payment. It allows the Merchant to get an authorisation from the Issuer keeping the amount captive in the Cardholders banking account; the transaction is authorised and the purchase will be triggered in a second moment, when the merchant needs to trigger a “Capture” on the Backoffice. 

Backoffice operations

At a back-office level, Cards supports the following types of operations: 

Capture

Used when the Cardholder has provided an authorisation for the payment on a 1st stage and the amount is captured. Used on a 2nd stage to execute the payment, which can happen in different ways (always triggered over an authorisation): 

• Full: capture the full amount authorised and finish the purchase; 
• Partial: split the capture and do several payments up to the total amount authorised. 

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: 

• Full: when the total amount of the purchase is refunded to the Cardholder; 
• Partial: when a subtotal of the total purchase is refunded to the Cardholder. 

Cancellation

Requests the cancellation of the amount (full or partial) of a previous authorisation. 

Merchant Initiated Transaction 

The purpose of this operation is to allow the Merchant to charge a service. In the first stage the Cardholder requests to register the payment as a Cardholder Initial Transaction and authorise the Merchant to do future debits (Merchant Initiated Transactions) in accordance with the service. 

Cardholder Initiated Transaction: needed to register as initial conditions. Authentication and consent collected from Cardholder.

Merchant Initiated Transaction: triggers following payments. 

Currently, two types of Merchant Initiated Transactions are accepted: 

• Recurring: Transactions processed at fixed, regular intervals not to exceed one year between Transactions, representing an agreement between a Cardholder and a Merchant to purchase goods or services provided over a period of time; 
  
  
• Unscheduled Card On File: A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regular occurring transaction date, where the Cardholder has provided consent for the Merchant to initiate one or more future transactions that are not initiated by the Cardholder.

It is possible to establish the relationship below among the Front office & Backoffice operations, having in mind that Backoffice operations will act on the Front office operations: 

1. A capture can act over an authorisation of the total or partial amount; 
2. An authorisation can be cancelled and the amount kept on hold will be released; 
3. An effective payment through a capture can only be refunded; 
4. An effective purchase only allows to trigger a refund in the Backoffice; 

Integration options

SIBS Gateway provides a collection of APIs that enables our Clients to process, manage payments and accept payments from banking cards. 

It is not necessary to choose all the SIBS Gateway payment solutions, our Clients can choose which API to use. 

Form integration

Simple form integration with javascript based widget, on three simple steps: 

Step 1: Prepare the checkout

Step 2: Get the payment status

Step 3: Merchant Notification: Receive payment status

Step 1: Prepare the checkout

Sends payment data, except payment method data. 

1. First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. The response to a successful request is a JSON with a transactionID, which is required in the second step to create the payment form.

2. Create the payment form: displays a payment form to allow customers to submit payment method data. 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 transactionID that was returned in the response from step 1.

<script src="https://{QLY/PRD}/assets/js/widget.js?id={transactionID}"></script> 

Change the variable in accordance with the environment – QLY or PRD

3. The {formContext} that you get in response from step 2.   

{formConfig}; 
{formStyle} (optionally)  

4. Configures the Merchant redirectUrl, which is the page on your website where the customer should be redirected after the payment.

5. Optional parameter that allows the user to change the form style. 

Step 2: Get the payment status

Once the payment is processed, the customer is redirect to your redirectUrl.

You can check the status of your transaction making a GET request.

Step 3: Merchant Notification: Receive payment status. 

SIBS Gateway will send the notification of the asynchronous payment status. 

Server-to-server integration

The Server to Server integration is also known as direct integration as it enables communication between the two servers, SIBS and Merchant. Cardholders can finalise a payment without being redirected to the SIBS Gateway Form. This integration is suitable for Merchants that store the payment data before sending them to the SIBS Payment Gateway. 

Financial operations

Step 1: Prepare the checkout

Step 2: Display payment method options to customer

Step 3: Update payment method data

Step 4: Get the payment status

Step 5: Merchant Notification: Receive payment status

For financial operations, Server-to-Server Integration is based on the following steps: 

Step 1: Prepare the checkout

Prepare the checkout: sends payment data, except payment method data. 

First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. The response to a successful request is a JSON with a transactionID, which is required in the second step. 

Step 2: Display payment method options to customer

The next step is to provide the payment method options and get payment data from the customer: 

• Card
• MULTIBANCO
• MB WAY ID
• Authorised payment

Step 3: Update payment method data

Sends payment method and its required data. 

Perform a payment request, call SIBS Gateway API with the collected data accordingly with the method. 

Step 4: Get the payment status

Get the payment status: gets the payment status. 

Step 5: Merchant Notification: Receive payment status. 

SIBS Gateway will send the notification of the asynchronous payments to the merchant server. 

Authorised Payments purpose is to facilitate the payment experience for your customers. 

Your customers can opt-in to have Authorised Payments for their business, that will simplify their purchases payment experience. 

There are two different types of Authorised Payments: 

• One Click: for one-off payments, in which the customer can perform purchases without the need of validation; 
• Subscription: automatic recurring payments (e.g. monthly, yearly subscriptions, etc.) without the need of customer authentication for each billing payment. 

Authorized Payments involves an initial authentication, conferred by the Cardholder to the Merchant, making it possible to make online purchases without further authentication steps. 

Activate 

In order to use the Authorized Payments functionalities in SIBS Backoffice, you will need to have a SIBS Payment Gateway offer with Authorized Payments included under contract with your financial institution.

Make sure you have access to a SIBS Backoffice account. If you haven’t had any onboarding process with SIBS regarding SIBS Backoffice, make sure you follow this link to receive credentials to access the platform. 

The activation of the Authorised Payments functionality is done via SIBS Backoffice. 

In order to activate Authorised Payments, go to “SIBS Payment Gateway 2.0” > “Authorised Payments”. 

This submenu is only visible for accounts with Owner or Administrator profile roles on SIBS Backoffice. 

If your merchant account does not have Authorised Payments activated yet, the screen will display an “Activate operative” button. 

Click on the button in order to activate Authorised Payments. 

This activation can only be performed if you have an Owner or Administrator profile role on SIBS Backoffice.

Configure 

In order to configure Authorised Payments, go to “Configuration” > “Authorised Payments”. 

There will be two distinct tabs in the page, that correspond to the two Authorised Payment types: 

• One Click: For one-off payments, in which the customer can perform purchases without the need for validation; 
• Subscription: Automatic payments for subscriptions (e.g. monthly, yearly subscriptions, etc.) without the need for customer authentication for each billing date payment. 

For each type of Authorised Payment, you should define your company’s name, logo and a link to the Terms and Conditions, that will be displayed in MB WAY. 

You will also be able to insert amount limits for the transactions of a given Authorised Payment. 

Integer values must be used when setting monthly limits for creating authorised payments, with the “Minimum value” of 1€ and the “Maximum value” of 9999€.

The customer, by using MB WAY, can set their limit value for the Authorised Payment related to a specific merchant. 

The change in the amount limits for a given Authorised Payment will only have an impact on tokens created after the new rule and will have no impact on the pool of tokens created until then.

Setup

In order to setup Authorised Payments in payments, you will need to configure your payment solutions.

To know more about setup Authorised Payments in payment solutions, click here.

Once every step of the setup is performed, all the purchases using Authorised Payments will be recorded on SIBS Backoffice. 

Check and filter

In order to see the list of the Authorised Payments performed, go to “SIBS Payment Gateway 2.0” > “Authorised Payments”. 

In this page, you can use the search bar to define “Quick filters” and easily search payments. 

The available filters are the following: 

Check specific transactions 

To check the transactions associated to a given Authorised Payment, click on the “Actions” button and then on the “Transactions” option, as shown below. 

SIBS Backoffice will redirect to the “Payment Operations” page, in which all the transactions for that specific Authorised Payment will be listed. 

The “SIBS Payment Gateway 2.0” menu has a submenu, “Payment Entities”, which allows to insert the Entities that will receive the Transactions. 

These Payment Entities must be inserted in SIBS Backoffice in order to perform the proper integration of MULTIBANCO references from vTerminal (SIBS Gateway 2.0). 

Insert Payment Entities

In the “SIBS Payment Gateway 2.0” > “APP SPG 2.0” you are able to generate and get the Client ID and Client Secret credentials needed in order to perform the SIBS Payment Gateway 2.0 integration. 

In order to generate the credentials, click on “Get”. You will be prompted to insert your password in order to confirm the credentials generation. 

If you already have a Client ID and Client Secret generated, the page will display a list with those credentials. 

In the “SIBS Payment Gateway 2.0” -> “Token Configuration” you can choose if you want Tokenisation at a merchant level or at a merchant and acceptor level. 

SIBS Backoffice will provide a token management according to the selected setting.