Search Overlay

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.

NOTETo 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:

  1. Create a payment handle with the following parameter settings:
    transactionType: PAYMENT
    paymentType: MULTIBANCO

  2. Pass the following parameter in the profile object of the payment handle request: 
    email: Email ID of the consumer. 

  3. 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.
  4. 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.

  5. 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.
  6. 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.

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

Payments flow diagram

Multibanco Refunds

To process a refund transaction for a Multibanco payment:

  1. Make sure the initial payment has a status of COMPLETED - you can only initiate a refund for a transaction where Settlement/Payment is completed.
  2. 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.
  3. 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:

  • The customer tries to pay but Skrill's provider declines the transaction.
  • The transaction is declined by Skrill’s internal fraud engine.

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:

  • The refund amount exceeds your account balance.
  • The refund amount exceeds the original payment amount.
  • Other generic errors transpire.