In-App Operative

The in-app operative aims at providing an integrated payment experience for the user who chooses the MB WAY service as the payment method in a Merchant app. This operative allows the communication between the Merchant mobile apps and the user’s MB WAY app, if installed in the same device, and supports the Purchase and Purchase Authorisation operations.

The integrity and security of the relationship between the Merchant app and the MB WAY app is ensured by tokens. This operative is based on a web service (MerchantAliasWSCreate) that allows to request a user
token creation at SIBS FPS. This token is used to invoke the MB WAY app.

The user token (aliasTypeCde ‘010’) may be reused for several purchases and, for this reason, the Merchant shall store the token assigned to the  his client. If the Merchant chooses not to store the token, then he must submit a new user token creation request.

This token is not visible to the MB WAY clients and it can only be removed through the MerchantAliasWSRemove web service.

Similarly to the other MB WAY integrations, this operative also includes all validations that ensure the Merchant compliance with the security requirements while submitting user token creation requests.

In this section, there are some Webhook notifications examples sent by SIBS Gateway, and the expected answer that the Merchant should give.
(More information in section Webhook Notification Response).

1. Webhook Notification Response

2. Webhook Notification Decryption

3. MB WAY Purchase with Alias

4. MB WAY Purchase with Alias – Declined

5. MB WAY Authorised Payment Creation

6. MB WAY Authorised Payment Purchase after Creation

7. Cancel MB WAY Authorised Payment

8. Cancel MB WAY Authorised Payment – Decline

9. Static QR Code Purchase

10. MULTIBANCO Reference Generation

11. MULTIBANCO Reference “Paid”

12. Card Purchase

13. Token Generation

14. Token Purchase

15. Merchant Initiated Transaction (MIT) with Type UCOF

16. Merchant Initiated Transaction (MIT) with Type Recurring

17. Cardholder Initiated Transaction (CIT) with Type UCOF

18. Cardholder Initiated Transaction (CIT) with Type Recurring

1. Webhook Notification Response

{
    "statusCode": "200",
    "statusMsg": "Success",
    "notificationID": "93b9b3a6-602f-4769-8158-48ae9c380ed5"
}

2. Webhook Notification Decryption

{
    “$cypher_algo = 'AES-256-GCM';
    $key = convert_encode($webhookSecret);
    $iv = convert_encode($iv_from_http_header);
    $auth = convert_encode($auth_tag_from_http_header);
    $data = convert_encode($http_body);
    $result = openssl_decrypt($data, $cypher_algo, $key, OPENSSL_RAW_DATA, $iv, $auth);”
}

3. MB WAY Purchase with Alias

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2efgrtgn456477",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": "16.20"
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e0085fw234",
        "terminalId": "99978",
        "merchantName": "Teste MBWAY Sucesso",
        "inApp": "false"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "MobilePhone",
        "value": "351#912345678"
    },
    "internalTransactionId": "S14073500001359S",
    "notificationID": "839ca363-8581-4b9f-8041-a6dfgrtyu643"
}

4. MB WAY Purchase with Alias – Declined

{
    "returnStatus": {
        "statusMsg": "Declined",
        "statusCode": "01.106.0004"
    },
    "paymentStatus": "Declined",
    "paymentMethod": "MBWAY",
    "transactionID": "s2nvtgbntiuybn88485t",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": "16.20"
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e00853de45",
        "terminalId": "99978",
        "merchantName": "Teste MBWAY Erro",
        "inApp": "false"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "MobilePhone",
        "value": "351#912345500"
    },
    "internalTransactionId": "S14073500001351S",
    "notificationID": "839ca363-8581-4b9f-8041-a6d456jkh678"
}

5. MB WAY Authorised Payment Creation

{
    "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,
        Notification: Restricted Version 2024.11 of 2024-11-11
        Reference: Page 125 of 151
        SIBS Gateway V2 Integration Manual
        “merchantName”: “Test Authorised Payment Creation”,
        “inApp”: “false”
    },
    "paymentType": "AUTH",
    "mbwayMandate": {
        "mandateIdentification": "12345690656800744652",
        "mandateAction": "CRTN",
        "mandateActionStatus": "SCCS",
        "mandateType": "SBSC",
        "clientName": "Andresa COS",
        "aliasMBWAY": "351#914341580"
    },
    "notificationID": "6e96b74f-ec33-4ca9-8cd3-1d00c5d82a0d"
}

6. MB WAY Authorised Payment Purchase after Creation

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MBWAY",
    "transactionID": "s2jrfvnriuv8tgt554tg",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": 15.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e0085dref45",
        "terminalId": 99978,
        "merchantName": "Teste Pagamentos Autorizados Sucesso"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "MobilePhone",
        "value": "351#919992314"
    },
    "internalTransactionId": "S13074000497973S",
    "notificationID": "839ca363-8581-4b9f-8041-a45tgbh67u"
}

7. Cancel MB WAY Authorised Payment

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "MANDATE",
    "transactionID": "s2t44gh56y67jAsftgt",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": 15.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e0085fd6789",
        "terminalId": 96546,
        "merchantName": "Canc Pagamento Autorizado"
    },
    "paymentType": "CAUT",
    "internalTransactionId": "S14072900000002S",
    "notificationID": "0d93a5ef-13e0-4a6b-9e40-652342321451"
}

8. Cancel MB WAY Authorised Payment – Decline

{
    "returnStatus": {
        "statusMsg": "Declined",
        "statusCode": "10.106.2662"
    },
    "paymentStatus": "Declined",
    "paymentMethod": "MANDATE",
    "transactionID": "s2SFFe3445gjn5hjas",
    "transactionDateTime": "2022-11-11T16:18:53.127Z",
    "amount": {
        "currency": "EUR",
        "value": 15.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e0085fd6ssd",
        "terminalId": 96546,
        "merchantName": "Canc Pagamento Autorizado"
    },
    "paymentType": "CAUT",
    "internalTransactionId": "S14072900000007S",
    "notificationID": "0d93a5ef-13e0-4a6b-9e40-h589085hnA "
}

9. Static QR Code Purchase

{
    "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": "NA",
            "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",
            Classification: Restricted Version 2024.11 of 2024-11-11
            Reference: Page 124 of 151
            SIBS Gateway V2 Integration Manual
            "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"
}

10. MULTIBANCO Reference Generation

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "REFERENCE",
    "transactionID": "s24587y857mtjgnbt",
    "transactionDateTime": "2022-12-23T10:48:39.153Z ",
    "amount": {
        "currency": "EUR",
        "value": "20.0"
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008sde23",
        "terminalId": "88845",
        "merchantName": "Teste Referências, Lda"
    },
    "paymentReference": {
        "reference": "256309828",
        "entity": "40200",
        "paymentEntity": "40200",
        "amount": {
        "value": "20.0",
        "currency": "EUR"
    },
    "status": "UNPAID",
    "expiryDate": "2022-01-23T10:48:39.153Z "
    },
    "paymentType": "PREF",
    "notificationID": "20273954-0540-4bd3-8e01-234eds234cds"
}

11. MULTIBANCO Reference “Paid”

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "REFERENCE",
    "transactionID": "s2jfvbiurbg8956vng",
    "transactionDateTime": "2022-12-23T10:48:39.153Z",
    "amount": {
        "currency": "EUR",
        "value": 20
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e00823sh76",
        "terminalId": 88845,
        "merchantName": "Teste Referências, Lda"
    },
    "paymentType": "PREF",
    "internalTransactionId": "S14073000000341S",
    "notificationID": "20273954-0540-4bd3-8e0-asd2w4jo0mmt"
}

12. Card Purchase

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2shdvbevr76756er",
    "transactionDateTime": "2022-11-11T16:18:53.127Z",
    "amount": {
        "currency": "EUR",
        "value": 19.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008456sw2",
        "terminalId": 66645,
        "merchantName": "Teste Cartões, Lda"
    },
    "paymentType": "PURS",
    "internalTransactionId": "S14073000000711S",
    "notificationID": "8ec13f91-0129-44ff-980c-79e456fds21s"
}

13. Token Generation

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "sandboxfghwTKNGEN000",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": 19.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008dsw212",
        "terminalId": 77745,
        "merchantName": "GOMERCIANTE DO LEGACY LD"
    },
    "paymentType": "AUTH",
    "token": {
        "tokenType": "Card",
        "value": "fjklvnrtinrt435356jv"
    },
    "internalTransactionId": "S13074000501340S",
    "notificationID": "462ec85b-5e1a-4a00-a4d7-97ddfe321567"
}

14. Token Purchase

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "TOKEN",
    "transactionID": "s2grnvtruigbitu845hhtn",
    "transactionDateTime": "2022-11-11T16:18:53.127Z ",
    "amount": {
        "currency": "EUR",
        "value": 19.2
    },
    "merchant": {
        "transactionId": "863b730df285443ca404e008mvn432kop",
        "terminalId": 77745,
        "merchantName": "PETROLEOS DE PORTUGAL - PETROGAL, SA"
    },
    "paymentType": "PURS",
    "token": {
        "tokenType": "Card",
        "value": "gbtyhyujyuikuier45646ger4"
    },
    "notificationID": "462ec85b-5e1a-4a00-a4d7-97d345fds234"
}

15. Merchant Initiated Transaction (MIT) with Type UCOF

{
    "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"
    }
}

16. Merchant Initiated Transaction (MIT) with Type Recurring

{
    "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"
    }
}

17. Cardholder Initiated Transaction (CIT) with Type UCOF

{
    "returnStatus": {
        "statusMsg": "Success",
        "statusCode": "000"
    },
    "paymentStatus": "Success",
    "paymentMethod": "CARD",
    "transactionID": "s2bDX8mjiFZU5ZwfvSvR",
    "transactionDateTime": "2023-01-06T16:57:11.2Z",
    "amount": {
        "currency": "EUR",
        "value": 102.38
    },
    "merchant": {
        "transactionId": "3064371",
        "terminalId": 45546,
        "merchantName": "GOMERCIANTE DO LEGACY"
    },
    "paymentType": "AUTH",
    "notificationID": "45d108d3-2cef-41a6-90af-a3bdb4af244a",
    "merchantInitiatedTransaction": {
        "type": "UCOF",
        "validityDate": "2023-01-31T00:00:00Z",
        "amountQualifier": "ESTIMATED"
    }
}

18. Cardholder Initiated Transaction (CIT) with Type Recurring

{
    "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"
        }
    }
}

In the event of an error in the merchant notification system, SIBS Gateway is ready to act and send notification retries to the merchant until the merchant confirms receipt of the notification.
When SIBS Gateway sends the Merchant Notification to the Merchant, the internal status of the notification remains “Requested” until the Merchant sends an acknowledgement to SIBS Gateway. If the merchant sends the acknowledgement, the notification status becomes “Processed” and the process ends, otherwise the Webhook Retry System is triggered at the end of a parameterised time.

The Webhook Retry System is a batch system that classifies merchant notifications with the status ‘Requested’ according to a minimum and maximum number of retries. This batch categorises merchant notifications into seven tiers, from Tier 0 (zero) to Tier 6 (six). Each tier has a specific retries count, a specific number of webhooks to retry and a retry period. Tier 0 represents the highest retry rate on the Webhook Retry System and Tier 6 represents the lowest retry rate in terms of periodicity.

The table below shows the seven categories of the Webhook Retry System, as well as the difference between them in terms of: Retries count, Number of webhooks retried and Retry period time. This batch process for a specific attempt will end after two months since the first attempt was started.

Tiers	Retries’ Count	Number of Webhooks Retried	Retry Period Time
Tier 0	0 to 4	400 (max)	Every 5 minutes
Tier 1	5 to 8	600 (max)	Every 1 hour
Tier 2	9 to 13	800 (max)	Every 2 hours
Tier 3	14 to 19	1000 (max)	Every 4 hours
Tier 4	20 to 26	1200 (max)	Every 6 hours
Tier 5	27 to 34	1400 (max)	Every 12 hours
Tier 6	35 to 43	1600 (max)	Every 24 hours

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

Complex Types

MerchantNotificationRequest  

Body

MerchantNotificationResponse

Body

Error message

Multibanco

Error code	Message to the Merchant	Message to the Client	Owner	What to do?
10.107.0001	Invalid payment entity	Entity not valid, Try again later.	Merchant	Please verify that the correct Merchant entity is being used.
10.107.0002	Invalid reference minimum amount	Invalid reference minimum, amount please try again.	Merchant	Please verify the parameterization in the amount
10.107.0003	Invalid reference maximum amount	Invalid reference maximum amount please try again.	Merchant	Please verify the parameterization in the amount
10.107.0004	Invalid currency	Invalid currency try again.	Merchant	Please verify the parameterization in the currency accepted
10.107.0005	Invalid NIB	Invalid NIB please try again.	Client	Please verify you are using the correct NIB
10.107.0006	Invalid reference initial date time	Invalid reference initial date time try again.	Merchant	Please verify the parameterization in time accepted
10.107.0007	Invalid reference limit date time	Invalid reference limit date time try again.	Merchant	Please verify the parameterization in time accepted
10.107.0008	Invalid Email	Invalid Email try again.	Client	Please insert the email used on the registration
10.107.0009	Payment entity is not active	Payment entity is not active, try later	Merchant	Please verify your entity, if it is the one in the SLA
10.107.0010	Reference generation not allowed for the payment entity	Reference generation not allowed try later.	Merchant	Please verify your entity, if it is the one in the SLA
10.107.0011	Payment reference not found	SIBS Internal error, Please try again later.	SIBS	SIBS Internal error, Please try again later.
10.107.0012	Payment reference is cancelled	Payment reference is cancelled.	Merchant	Please verify your reference was cancelled.
10.107.0013	Payment reference already paid	Payment reference already paid.	Merchant	Please verify your reference is already paid.
10.107.0014	Invalid operation	Invalid operation, try later.	SIBS	SIBS Internal error, Please try again later.
90.000.0001	Exception	SIBS Technical Issue try again later	SIBS	Please try Again or later – Issue to be solved by SIBS
90.000.0003	Error in message format	SIBS Technical Issue try again later	SIBS	Please try Again or later – Issue to be solved by SIBS

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. 

PCI 3-Step Process

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: 

	Purchase	Authorisation	Capture
Capture		1
Refund	4		3
Cancellation		2

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> 

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.

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 

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

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. 

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. 

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

Setup

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

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: 

Field	Description
ID	ID number of the Authorised Payment
Name	Name of the card holder
Monthly limit value	Monthly limit value defined for the Authorised Payment
Authorised payment type	Type of Authorised Payment (if One-Click or Subscription)
Expiration date	Expiration date of the Authorised Payment
Phone number	Customer phone number used in the Authorised Payment
Creation date	Creation date of Authorised Payment
Status	Status of the Authorised Payment (if “Active”, “Suspended, “Cancelled” or “Expired”)
Original transaction ID	Transaction ID of the Authorised Payment

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 order to insert Payment Entities in SIBS Backoffice, you will need to have a credential created. See here how to create one.

In the Payment Entities page, there will be a form named “Insert your Payment Entity”.

Complete the form by entering the correct ‘Payment Entity’ (provided by the Onboarding team—contact them if needed) and a clear ‘Description’ to help you easily identify the payment entity. Then click ‘Confirm’ to proceed.

The inserted Payment Entity will then be displayed on the page list. Here you can use the Quick Filters to easily find your Payment Entities.