MB WAY via Skrill Quick Checkout
MB WAY, the leading payments app in Portugal, is a digital wallet for mobile payments. It was developed on the SIBS Multibanco scheme, with more than 1 million customers and a wide network of participating merchants. Customers can link a debit or credit card to a mobile phone number, then shop or make immediate transfers using their phone number and an MB WAY PIN.
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 MB WAY, you must be onboarded with Skrill's solution.
Transaction Types
We support the following transaction types:
- Payments
- Refunds
Typical Scenarios
MB WAY Payments
To process a payment request using MB WAY as the payment type:
-
Create a payment handle with the following parameter settings:
transactionType: PAYMENT
paymentType: MBWAY -
Pass the following parameters in the profile object of the payment handle request:
email: Email ID of the consumer.
phone: Phone number of the customer that is linked to their MB Way app. -
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 and confirm their MB WAY phone number. -
The customer receives an in-app notification through the MB WAY app and logs into the app to finish the transaction.
-
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
MB WAY Refunds
To process a refund transaction for a MB WAY 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 an MB WAY payment:
{
"merchantRefNum": "c057227d-dce5-4855-8b2e-84e76738fcc4",
"transactionType": "PAYMENT",
"paymentType": "MBWAY",
"amount": 500,
"currencyCode": "EUR",
"profile": {
"firstName": "John",
"lastName": "Cena",
"phone": "8074683324",
"email": "mohan@paysafe.com"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
}
]
}
Payment Handle response
Response to a payment handle creation request:
{
"id": "891e328b-e3b1-4001-bd87-fee9722069ba",
"paymentType": "MBWAY",
"paymentHandleToken": "PHEJPRvbwXCuVD8r",
"merchantRefNum": "1f94971c-b415-4781-841f-6ab866f26527",
"currencyCode": "EUR",
"txnTime": "2023-06-09T10:41:57Z",
"customerIp": "10.195.93.135",
"status": "INITIATED",
"links": [
{
"rel": "redirect_payment",
"href": "https://api.qa.paysafe.com/alternatepayments/v1/redirect?accountId=1021949450&paymentHandleId=891e328b-e3b1-4001-bd87-fee9722069ba&token=eyJhbGciOiJIUzI1NiJ9.eyJhY2QiOiIxMDIxOTQ5NDUwIiwicHlkIjoiODkxZTMyOGItZTNiMS00MDAxLWJkODctZmVlOTcyMjA2OWJhIiwiZXhwIjoxNjg2MzA5MTE4fQ.qqONnyn8Q7enm2Rtm9afiHOSd-LU845wKmQCYJRo6WE"
}
],
"liveMode": false,
"simulator": "EXTERNAL",
"usage": "SINGLE_USE",
"action": "REDIRECT",
"executionMode": "SYNCHRONOUS",
"amount": 500,
"timeToLiveSeconds": 899,
"gatewayResponse": {
"processor": "SKRILL_QCO",
"sid": "9c3050520e819beeec5110301f90e3f9"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
}
],
"transactionType": "PAYMENT",
"gatewayReconciliationId": "c97fdfdc-a0bd-453b-8316-5a0daee9c60a",
"updatedTime": "2023-06-09T10:41:58Z",
"statusTime": "2023-06-09T10:41:58Z",
"profile": {
"firstName": "John",
"lastName": "Cena",
"email": "mohan@paysafe.com",
"phone": "8074683324"
}
}
Payment request
MB WAY payment request using the paymentHandleToken received in the payment handle response:
{
"amount": 500,
"merchantRefNum": "1686307378",
"paymentHandleToken": "PHEJPRvbwXCuVD8r"
}
Payment response
Response to an MB WAY payment request:
{
"id": "5c4da34a-64b2-4f4f-a52f-08d1d8211a52",
"paymentType": "MBWAY",
"paymentHandleToken": "PHEJPRvbwXCuVD8r",
"merchantRefNum": "1686307451",
"currencyCode": "EUR",
"settleWithAuth": true,
"dupCheck": true,
"txnTime": "2023-06-09T10:41:57Z",
"customerIp": "10.195.93.135",
"status": "COMPLETED",
"gatewayReconciliationId": "c97fdfdc-a0bd-453b-8316-5a0daee9c60a",
"amount": 500,
"availableToRefund": 500,
"consumerIp": "10.195.93.135",
"liveMode": false,
"simulator": "EXTERNAL",
"updatedTime": "2023-06-09T10:44:12Z",
"statusTime": "2023-06-09T10:44:12Z",
"gatewayResponse": {
"transaction_id": "c97fdfdc-a0bd-453b-8316-5a0daee9c60a",
"amount": "5.00",
"mb_transaction_id": "326349844",
"pay_from_email": "mohan@paysafe.com",
"pay_to_email": "elvisstoyanov.qco@sun-fish.com",
"currency": "EUR",
"merchant_id": "298847640",
"id": "326349844",
"processor": "SKRILL_QCO",
"status": "2",
"sid": "9c3050520e819beeec5110301f90e3f9"
},
"availableToSettle": 0,
"profile": {
"firstName": "John",
"lastName": "Cena",
"email": "mohan@paysafe.com",
"phone": "8074683324"
},
"settlements": {
"amount": 500,
"txnTime": "2023-06-09T10:41:57.000+0000",
"availableToRefund": 500,
"merchantRefNum": "1686307451",
"id": "5c4da34a-64b2-4f4f-a52f-08d1d8211a52",
"status": "COMPLETED"
}
}
Refund request
Refund request for an MB WAY payment:
{
"amount": 50,
"merchantRefNum": "1686307506"
}
Refund response
Response to an MB WAY refund request:
{
"id": "28d955ca-3067-4a4b-bde8-1322a7234707",
"paymentType": "MBWAY",
"merchantRefNum": "1686307992",
"currencyCode": "EUR",
"txnTime": "2023-06-09T10:53:12Z",
"status": "COMPLETED",
"gatewayReconciliationId": "4841419552",
"amount": 550,
"updatedTime": "2023-06-09T10:53:12Z",
"statusTime": "2023-06-09T10:53:12Z",
"liveMode": false,
"simulator": "EXTERNAL",
"gatewayResponse": {
"id": "4841419552",
"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 create the payment call on your behalf:
- Auto-settlement: After the payment handle expires in fifteen minutes (timeToLiveSeconds), you will receive a notification via the PAYMENT_HANDLE_EXPIRED webhook. Next, Paysafe's system will initiate the Payments API call independently, making completing the payment/settlement procedure easier. You will receive notifications for successful payment and settlement via PAYMENT_COMPLETED and SETTLEMENT_COMPLETED webhooks.
- Auto-settlement and Auto-refund: After the expiry of the payment handle in fifteen minutes (timeToLiveSeconds), you will receive a notification through 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 by triggering 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 MB WAY:
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:
|