Multibanco via Skrill Quick Checkout
Multibanco is a popular payment method used in Portugal where a order reference ID is generated during checkout. Customers can then use the order reference to pay through their online bank, or by using an ATM or point of sale device. The Multibanco service is supported by all major banks in Portugal and is therefore accessible to the maximum number of customers.
Features
- Supported region: Portugal.
- Supported currency: EURO.
Setup Requirements
To create accounts in both the sandbox and production environments we need the following details:
- Your Skrill Pay to email address.
- Your Skrill account API/MQI password.
NOTE: To offer Multibanco payments, you must be onboarded with Skrill's solution.
Transaction Types
We support the following transaction types:
- Payments
- Refunds
Typical Scenarios
Multibanco Payments
To process a payment request using Multibanco as the payment type:
-
Create a payment handle with the following parameter settings:
transactionType: PAYMENT
paymentType: MULTIBANCO -
Pass the following parameter in the profile object of the payment handle request:
email: Email ID of the consumer. -
We return a payment handle response with the following details:
- The action parameter set to REDIRECT.
- A redirect_payment link pointing to the Skrill redirect URL.
- A payment handle status of INITIATED.
-
Redirect the customer to the Skrill page (using redirect_payment).
If you didn't send the customer's First Name and Last Name in the payment handle request, the customer can now provide these details. -
The customer receives a Reference ID which they can use to complete payment using one of the following options:
- Using an ATM or POS: the customer selects the Multibanco payment method and enters the order reference ID.
- Through online banking: the customer logs in to their online bank and pays by bank transfer using the Multibanco order reference ID.
-
Depending on the status of the transaction, the customer is redirected to either your success or failed page.
The status of the payment handle changes to PAYABLE if the transaction is successful, or FAILED if it is unsuccessful - you will be notified of this status change via your configured webhooks. -
Use the paymentHandleToken returned in the response to process the payment request.
NOTE: You should store the payment ID returned in the response in case you need to process a refund. The payment ID is needed to deposit refunds directly into the bank account that was used for the original transaction.
APIs to use
Payments flow diagram
Multibanco Refunds
To process a refund transaction for a Multibanco payment:
- Make sure the initial payment has a status of COMPLETED - you can only initiate a refund for a transaction where Settlement/Payment is completed.
- Create a refund request using the payment ID received in the initial payment response:
POST: /paymenthub/v1/settlements/{paymentId}/refunds
NOTE:- The refund amount can be equal to the initial payment, or lower if you want to make a partial refund.
- If required, you can initiate multiple partial refunds until the total refund amount is less than or equal to the initial payment amount.
- We return a refund response containing details of the completed payment and a unique identifier for referring to each individual refund (partial or full).
The status of the refund changes from PENDING to COMPLETED when the refund is processed - you will be notified of all status changes via your configured webhooks.
APIs to use
Refunds flow diagram
Code Examples
Payment Handle request
Payment handle request for a Multibanco payment:
{
"merchantRefNum": "d254956e-5700-47ee-87f1-ffe6aff84abd",
"transactionType": "PAYMENT",
"paymentType": "MULTIBANCO",
"amount": 21000,
"currencyCode": "EUR",
"profile": {
"firstName": "John",
"lastName": "Cena",
"email": "nagababu@paysafe.com"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
}
]
}
Payment Handle response
Response to a payment handle creation request:
{
"id": "e54965d9-6625-49df-afde-478d534624fc",
"paymentType": "MULTIBANCO",
"paymentHandleToken": "PHl4Ba8c4ENf1dtF",
"merchantRefNum": "0845d0df-c78f-4123-ba94-b386dabbf610",
"currencyCode": "EUR",
"txnTime": "2023-06-19T11:26:40Z",
"customerIp": "115.114.129.142",
"status": "INITIATED",
"links": [
{
"rel": "redirect_payment",
"href": "https://api.test.paysafe.com/alternatepayments/v1/redirect?accountId=1002670190&paymentHandleId=e54965d9-6625-49df-afde-478d534624fc&token=eyJhbGciOiJIUzI1NiJ9.eyJhY2QiOiIxMDAyNjcwMTkwIiwicHlkIjoiZTU0OTY1ZDktNjYyNS00OWRmLWFmZGUtNDc4ZDUzNDYyNGZjIiwiZXhwIjoxNjg3MTc1ODAwfQ.FP5ZIPoTz0xMFIo56t1nxKgyVreSUPGaSIvEzsK0YLA"
}
],
"liveMode": false,
"simulator": "EXTERNAL",
"usage": "SINGLE_USE",
"action": "REDIRECT",
"executionMode": "SYNCHRONOUS",
"amount": 21000,
"timeToLiveSeconds": 899,
"gatewayResponse": {
"processor": "SKRILL_QCO",
"sid": "0b8a3a67c1ee9bd3293fdbb861282f7b"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
}
],
"transactionType": "PAYMENT",
"gatewayReconciliationId": "0d1bbdd9-06a6-4ccc-9432-0aa315e73cea",
"updatedTime": "2023-06-19T11:26:40Z",
"statusTime": "2023-06-19T11:26:40Z",
"profile": {
"firstName": "John",
"lastName": "Cena",
"email": "nagababu@paysafe.com"
}
}
Payment request
Multibanco payment request using the paymentHandleToken received in the payment handle response:
{
"amount": 21000,
"merchantRefNum": "1687174097",
"paymentHandleToken": "PHl4Ba8c4ENf1dtF"
}
Payment response
Response to a Multibanco payment request:
{
"id": "af355323-e87a-4b58-8cc0-f7c110c56351",
"paymentType": "MULTIBANCO",
"paymentHandleToken": "PHl4Ba8c4ENf1dtF",
"merchantRefNum": "1687174126",
"currencyCode": "EUR",
"settleWithAuth": true,
"dupCheck": true,
"txnTime": "2023-06-19T11:26:40Z",
"customerIp": "115.114.129.142",
"status": "COMPLETED",
"gatewayReconciliationId": "0d1bbdd9-06a6-4ccc-9432-0aa315e73cea",
"amount": 21000,
"availableToRefund": 21000,
"consumerIp": "115.114.129.142",
"liveMode": false,
"simulator": "EXTERNAL",
"updatedTime": "2023-06-19T11:28:46Z",
"statusTime": "2023-06-19T11:28:46Z",
"gatewayResponse": {
"transaction_id": "0d1bbdd9-06a6-4ccc-9432-0aa315e73cea",
"amount": "210.00",
"mb_transaction_id": "4857014753",
"pay_from_email": "nagababu@paysafe.com",
"pay_to_email": "monika-testmerchant@paysafe.com",
"currency": "EUR",
"merchant_id": "202454978",
"id": "4857014753",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "0b8a3a67c1ee9bd3293fdbb861282f7b"
},
"availableToSettle": 0,
"profile": {
"firstName": "John",
"lastName": "Cena",
"email": "nagababu@paysafe.com"
},
"settlements": {
"amount": 21000,
"txnTime": "2023-06-19T11:26:40.000+0000",
"availableToRefund": 21000,
"merchantRefNum": "1687174126",
"id": "af355323-e87a-4b58-8cc0-f7c110c56351",
"status": "COMPLETED"
}
}
Refund request
Refund request for a Multibanco payment:
{
"amount": 2421,
"merchantRefNum": "1687174150"
}
Refund response
Response to a Multibanco refund request:
{
"id": "c1635200-6fd7-4da3-a089-593ead3ab403",
"paymentType": "MULTIBANCO",
"merchantRefNum": "1687174163",
"currencyCode": "EUR",
"txnTime": "2023-06-19T11:29:23Z",
"status": "COMPLETED",
"gatewayReconciliationId": "4857016162",
"amount": 2421,
"updatedTime": "2023-06-19T11:29:24Z",
"statusTime": "2023-06-19T11:29:24Z",
"liveMode": false,
"simulator": "EXTERNAL",
"gatewayResponse": {
"id": "4857016162",
"status": "2",
"merchant_id": "202454978",
"processor": "SKRILL_QCO"
},
"source": "SingleAPI"
}
Automatic Settlements and Refunds
If you do not make a Payments API call and have automatic settlements and refunds turned on, the Paysafe system will automatically make the payment call on your behalf:
- Auto-settlement: When the payment handle expires after fifteen minutes (timeToLiveSeconds), you will be notified via the PAYMENT_HANDLE_EXPIRED webhook. Next, the Paysafe's system will initiate the Payments API call on its own, making it easier to complete the payment/settlement procedure. You will be notified of the successful payment and settlement by triggering the PAYMENT_COMPLETED and SETTLEMENT_COMPLETED webhooks.
- Auto-settlement and Auto-refund: When the payment handle expires after fifteen minutes (timeToLiveSeconds), you will be notified via the PAYMENT_HANDLE_EXPIRED webhook. The Paysafe's system seamlessly establishes the Payments API call, ensuring that all payment, settlement, and refund processes are completed successfully. You will be notified of these events through the triggering of the PAYMENT_COMPLETED, SETTLEMENT_COMPLETED, and REFUND_COMPLETED webhooks.
To enable automatic settlements and refunds, contact Integration Support.
Webhooks
You can trigger the following webhooks for Multibanco:
Payment Handle webhooks
| Webhook | Description |
|---|---|
| PAYMENT_HANDLE_PAYABLE | The payment handle token has been successfully created and can be used for the payment call when the preliminary requirements are completed. |
| PAYMENT_HANDLE_PROCESSING | The customer was successfully redirected to the payment platform's page and has started the payment process. |
| PAYMENT_HANDLE_COMPLETED | The payment handle process was completed and the associated payment call has been initiated. |
| PAYMENT_HANDLE_EXPIRED | The next step was not initiated within the specified time frame (timeToLiveSeconds) after the payment handle was created. NOTE: timeToLiveSeconds is returned in the payment handle response and represents the number of seconds the paymentHandleToken is valid before expiration. |
| PAYMENT_HANDLE_FAILED | The customer was successfully redirected to the payment platform's page but a technical error occurred and we didn't receive the final communication. |
Payments webhooks
| Webhook | Description |
|---|---|
| PAYMENT_PROCESSING | The payment is in progress. In some cases, delays can occur due to pending actions by either the customer or by you. |
| PAYMENT_PENDING | The payment is pending because the transaction hasn't yet completed from the customer's bank account to the Skrill wallet to you. |
| PAYMENT_COMPLETED/ SETTLEMENT_COMPLETED | The payment was completed successfully. |
| PAYMENT_FAILED | The payment failed during the payment process. |
Refund webhooks
| Webhook | Description |
|---|---|
| REFUND_FAILED | The refund was initiated but failed due to a functional error. For example, the refund amount was more than the payment amount. |
| REFUND_COMPLETED | The refund was successfully transferred from your merchant account to the customer's chosen bank account. |
| REFUND_PENDING | The refund has been initiated but due to various bank delays or time zone issues the actual money transfer has not yet happened. |
Refund Simulations
You can simulate COMPLETED and FAILED refund transactions using our internal simulator.
- Pass INTERNAL as the simulator field value in your request header.
- Send the following refund amounts in your requests to simulate the desired outcome:
| Refund Amount | Initial Status | Next Status Transition | Status Transition Delay (in seconds) |
|---|---|---|---|
| 24.21 | PENDING | COMPLETED | 5 |
| 24.31 | PENDING | FAILED | 10 |
| 26.31 | FAILED | FAILED | 0 |
- If the refund amount exceeds the original payment amount, the refund has a status of FAILED.
- For any other refund transaction amounts, the refund has a status of COMPLETED.
Error Codes
Initiate payment error codes
| Skrill PSP Return code | Message Code | Paysafe HTTP Code | Paysafe Error Code | Paysafe Error Message | Paysafe Error Details | Paysafe status | Comments |
|---|---|---|---|---|---|---|---|
| -2 | failed | 502 | 1001 | External Gateway Error | An external Gateway error occurred. | FAILED | Typically occurs when:
|
Initiate refund error codes
| Skrill PSP Return code | Message Code | Paysafe HTTP Code | Paysafe Error Code | Paysafe Error Message | Paysafe Error Details | Paysafe status | Comments |
|---|---|---|---|---|---|---|---|
| -2 | failed | 502 | 1001 | External Gateway Error | An external Gateway error occurred. | FAILED | Typically occurs when:
|