Skip to main content

MB WAY

MB WAY is Portugal's most widely used mobile payment wallet. Shoppers pay with the phone number linked to their MB WAY app and approve each payment in the app, with no card details entered at checkout.

MB WAY lets shoppers pay at checkout with their phone number and approve the payment in the MB WAY app.MB WAY lets shoppers pay at checkout with their phone number and approve the payment in the MB WAY app.

Mobile push notifications​

The shopper enters their phone number at checkout. MB WAY sends a payment request to the shopper's app, where they review the amount, choose a card, and approve with their PIN.

  • Pay via phone number with no card entry
  • Payment approved in the MB WAY app
  • Supported by most Portuguese banks

Details​

Country Portugal
Currency EUR
InputPhone number
Integrations Direct API

Capabilities​

Refunds
Partial refunds
Final amount captured later
Multiple partial captures
Incremental authorizations
Disputes
Recurring payments
Split payments
Flow TypesImmediateRecurring

Flows

MB WAY Payment​

This flow works for ONE_TIME transaction types.

Steps​

  1. Shopper selects MB WAY and enters their phone number.
info

The phone number must be registered with MB WAY.

  1. Merchant Initiates Payment with Nopan. The payment stays pending while the shopper approves it.
  2. MB WAY sends a push notification to the shopper's MB WAY app.
  3. Shopper reviews the payment, chooses a card, and approves it with their PIN.
  4. Nopan notifies merchant about transaction being completed.
  5. Alternatively merchant periodically checks for the status of transaction.
warning

The shopper has 4 minutes to approve the payment in the MB WAY app. If they don't approve in time, the payment is declined with reason code 2000. If they reject the request, the reason code is 5005. Show the shopper that the payment is waiting for approval in their app.

Integration​

Send a POST /payments/initiate request to Nopan with the following format:

{
  "processingAccountId": "merchant-1234",
  "clientTransactionId": "client-txn-7f3a91d2",
  "returnUrl": "https://api.merchant.callback?ref=order-1234",
  "transactionType": "ONE_TIME",
  "paymentDetails": {
    "amount": 2500,
    "currency": "EUR",
    "country": "PT",
    "description": "Product ID 1234 purchase"
  },
  "providerDetails": {
    "providerId": "MBWAY"
  },
  "payerDetails": {
    "payerId": "payerUUID",
    "phone": {
      "number": "912345678",
      "countryCode": "+351"
    }
  },
  "requestContext": {
    "ipAddress": "203.0.113.45",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15",
    "channel": "WEB",
    "deviceId": "device-67890",
    "locale": "pt-PT"
  },
  "metadata": {
    "orderId": "12345",
    "customerId": "cust-789"
  }
}
tip

payerDetails.phone is required. Use the phone number linked to the shopper's MB WAY account.

MB WAY Authorization​

This flow works for RECURRING and TOKEN_ONLY transaction types.

The shopper authorizes the merchant once in the MB WAY app. When approving, the shopper sets a maximum amount and an expiry date for the authorization. Later charges don't need the shopper to approve them.

Steps​

  1. Shopper selects MB WAY and enters their phone number.
  2. Merchant Initiates Payment with Nopan, with a RECURRING or TOKEN_ONLY transaction type.
  3. MB WAY sends a push notification to the shopper's MB WAY app.
  4. Shopper reviews the authorization, sets the maximum amount and expiry date, and approves it.
  5. For RECURRING , Nopan charges the first payment straight away. For TOKEN_ONLY , no money is moved until the merchant sends a charge request.
  6. Nopan notifies the merchant about the transaction being completed.
warning

The shopper has 10 minutes to approve the authorization in the MB WAY app. If they don't approve in time, or reject the request, the authorization isn't created.

Integration​

Send a POST /payments/initiate request to Nopan with the following format:

{
  "processingAccountId": "merchant-1234",
  "clientTransactionId": "client-txn-9b2e47c1",
  "returnUrl": "https://api.merchant.callback?ref=order-1234",
  "transactionType": "TOKENIZED",
  "paymentDetails": {
    "amount": 2000,
    "currency": "EUR",
    "country": "PT",
    "description": "Subscription ID 1234",
    "recurringFirstPaymentAt": "2026-12-01T10:00:00.000Z"
  },
  "providerDetails": {
    "providerId": "MBWAY"
  },
  "payerDetails": {
    "payerId": "payerUUID",
    "phone": {
      "number": "912345678",
      "countryCode": "+351"
    }
  }
}
tip

payerDetails.phone is required. Use the phone number linked to the shopper's MB WAY account.

info

MB WAY authorizations have no billing frequency. Don't send recurringFrequency for MB WAY.

MB WAY Recurring​

This flow works only with RECURRING and TOKEN_ONLY transaction types, after the shopper has approved the authorization.

Steps​

  1. Merchant sends Nopan a Charge Request.
  2. Nopan charges the shopper with MB WAY, using the authorization the shopper approved. The shopper doesn't need to approve the charge.
  3. Nopan confirms the result to the merchant.
warning

A charge is declined if it's above the maximum amount the shopper set, or after the authorization's expiry date. The shopper can also suspend or cancel the authorization in the MB WAY app at any time.

Integration​

Send a POST /payments/charge request to Nopan with the following format:

{
  "clientTransactionId": "order123",
  "transactionType": "RECURRING",
  "paymentDetails": {
    "amount": 2000,
    "currency": "EUR",
    "country": "PT",
    "description": "Subscription ID 1234"
  },
  "providerDetails": {
    "providerId": "MBWAY"
  },
  "payerDetails": {
    "payerId": "payerUUID",
    "paymentToken": "paymentTokenUUID"
  }
}
tip

paymentToken or payerId is required.

Testing​

Leverage Nopan Mocking framework to test your MB WAY integration with Nopan.

Error Codes​

info

For a full list of Nopan error codes, see Error Handling.

MB WAY Code
Nopan Reason Code
Description
Action
01.106.0001 – Refused by the shopper
5005
The shopper rejected the payment in the MB WAY app.
Adjust Logic
01.106.0002 – Card already associated
1010
The card is already associated with another MB WAY alias.
Adjust Logic
10.106.0003 – Wrong alias
2002
The phone number is not a valid MB WAY alias.
Fix Request
10.106.0004 – Alias format
4000
The phone number format is invalid.
Fix Request
10.106.0005 – Alias duplication
2002
The phone number is duplicated.
Fix Request
10.106.0006 – Alias does not exist
2002
The phone number is not registered with MB WAY.
Fix Request
10.106.0007 – Duplicated transaction
3002
A transaction with the same identifier has already been processed.
Adjust Logic
10.106.0009 – Operation declined
1010
The operation was declined.
Adjust Logic
90.000.0002 – Time out
8001
The MB WAY service timed out.
Retry
10.106.0002 – Service unavailable
8004
The MB WAY service is temporarily unavailable.
Retry

Recurring and tokenized payments​

These codes apply to the MB WAY authorization used for RECURRING and TOKEN_ONLY payments, and to charges made with it.

MB WAY Code
Nopan Reason Code
Description
Action
10.106.2632 – Authorized Payment Unknown
8004
MB WAY could not process the authorization. Issue on the MB WAY side.
Retry
10.106.2639 – Authorized Payment Invalid Operation Type
8004
MB WAY could not process the authorization. Issue on the MB WAY side.
Retry
10.106.2640 – Authorized Payments Service Disabled
8004
The MB WAY authorization service is temporarily unavailable.
Retry
10.106.2641 – Invalid Authorized Payment Status
8004
MB WAY could not process the authorization. Issue on the MB WAY side.
Retry
10.106.2644 – Invalid Authorized Payment Values
8004
MB WAY could not process the authorization. Issue on the MB WAY side.
Retry
10.106.2645 – Invalid Authorized Payment Service Provider
8004
MB WAY could not process the authorization. Issue on the MB WAY side.
Retry
10.106.2699 – Invalid Authorized Payment Context
8004
MB WAY could not process the authorization. Issue on the MB WAY side.
Retry
90.106.2699 – Internal error
8004
MB WAY internal error.
Retry
10.110.2301 – Status validation error
5002
The authorization is not in a status that allows this operation.
Adjust Logic
10.110.2631 – Authorization cancelled
5005
The authorization request was cancelled.
Adjust Logic
10.110.2632 – Authorization unknown
4001
The authorization request does not exist.
Fix Request
10.110.2633 – Authorization rejected
5005
The shopper rejected the authorization in the MB WAY app.
Adjust Logic
10.110.2634 – Authorization refused
1010
The authorization was refused.
Adjust Logic
10.110.2635 – Authorization reverted
5004
The authorization was reverted.
Adjust Logic
10.110.2636 – Authorization time out
2000
The shopper did not approve the authorization in the MB WAY app in time.
Retry
10.110.2637 – Authorization expired
2000
The authorization request expired before the shopper approved it.
Retry
10.110.2638 – Authorization unknown
4001
The authorization request does not exist.
Fix Request
10.110.2639 – Authorization not valid
5002
The authorization request is not in a valid status for this operation.
Adjust Logic
10.110.2640 – Authorization inactive
5004
The authorization is inactive, for example suspended by the shopper.
Adjust Logic
10.110.2641 – Authorization not valid
5002
The authorization request is not in a valid status for this operation.
Adjust Logic
10.110.2642 – Authorization token not valid
4060
The payment token is not valid.
Fix Request
10.110.2643 – Invalid authorization context
4000
The request is incomplete or incorrectly filled in.
Fix Request
10.110.2670 – Invalid terminal
2003
The account is not set up correctly for MB WAY recurring and tokenized payments.
Contact Support
10.110.2671 – Invalid payment method
2003
The account is not set up correctly for MB WAY recurring and tokenized payments.
Contact Support
10.110.2672 – Invalid authorization identification
4000
The request contains an authorization identification where none is expected.
Fix Request
10.110.2673 – Missing authorization data
4000
Required authorization data is missing.
Fix Request
10.110.2674 – Merchant authorization service inactive
2003
MB WAY recurring and tokenized payments are not enabled for this account.
Contact Support
10.110.2675 – Authorization already exists
5001
The shopper already has an authorization with the same data.
Adjust Logic
10.110.2676 – Authorization unavailable
4060
The authorization is unavailable.
Fix Request
10.110.2677 – Authorization unknown
4060
The authorization does not exist.
Fix Request
10.110.2678 – Authorization cancelled
4061
The authorization was cancelled. Ask the shopper for a new authorization.
Adjust Logic
10.110.2680 – Wrong authorization parameters
4000
The authorization request parameters are not valid.
Fix Request
10.110.2681 – Wrong authorization parameters
4000
The authorization request parameters are not valid.
Fix Request

Requirements​

  • Shopper must have an MB WAY account linked to a participating Portuguese bank.
  • Shopper must approve the payment in the MB WAY app.
  • Recurring and tokenized payments require the shopper to approve an authorization in the MB WAY app.

Learn More​

Learn more on MB WAY website.