MB_WAY

MB WAY is a digital wallet that allows customers in Portugal to authorize payments using the mobile phone number registered with their MB WAY account.

Overview

Property	Details
Markets (consumer)	`PT`
Consumer currencies	`EUR`
Authentication methods	`APP_AUTHORIZATION`
Authentication timeout	Subject to channel rules
Minimum payment amount	Subject to channel rules
Maximum payment amount	Subject to channel rules
Payment instrument	`DIGITAL_WALLET`
One-time payment	Yes
Recurring payments	No
Separate captures	No
Refund	Full · Partial
Refund validity	Subject to channel rules
Disputes	Subject to channel rules
Supported products	`Checkout Session` · `Hosted Checkout` · `Embedded Checkout` · `API`

Payment Flow

Customer selects MB WAY at checkout.

The merchant provides the customer's MB WAY phone number in payment_method_data.billing.phone.

UseePay validates that the phone number is in E.164 format and initiates the MB WAY payment.

The customer receives a payment authorization notification in the MB WAY app.

UseePay returns mb_way_await_authorization while waiting for the customer to approve the payment.

The customer reviews and authorizes the payment in the MB WAY app.

UseePay updates the PaymentIntent and sends a webhook notification containing the final payment status.

Notes

MB WAY is primarily available to customers in Portugal.

The payment currency is EUR.

payment_method_data.billing.phone is required.

The phone number must use the international E.164 format:

+351912345678

Do not include spaces, parentheses or hyphens:

351 912 345 678

MB WAY only supports automatic capture. Set auto_capture to true or omit it to use the default value.

MB WAY authorization is completed asynchronously in the customer's mobile app. The initial API response does not mean that the payment has succeeded.

Always retrieve the PaymentIntent or process the webhook notification before fulfilling the order.

The payment_method_data.mb_way object currently does not require any MB WAY-specific business parameters. The optional extra_params object is reserved for extended channel parameters and should only be provided when instructed by UseePay.

Integration Guide

Create and Confirm a PaymentIntent

UseePay recommends creating and confirming the PaymentIntent in a single request by setting confirm to true.

Set:

currency to EUR

payment_method_data.type to mb_way

payment_method_data.billing.phone to a valid E.164 phone number

billing.address.country to PT

confirm to true

auto_capture to true

A return_url should still be provided to maintain a consistent payment integration, although customer authorization is completed in the MB WAY app.

Request Example

{
  "merchant_order_id": "order_mb_way_001",
  "amount": 1000,
  "currency": "EUR",
  "confirm": true,
  "auto_capture": true,
  "return_url": "https://merchant.example.com/payment/return",
  "payment_method_data": {
    "type": "mb_way",
    "billing": {
      "first_name": "Maria",
      "last_name": "Silva",
      "email": "maria.silva@example.com",
      "phone": "+351912345678",
      "address": {
        "country": "PT"
      }
    },
    "mb_way": {}
  }
}

Request Example (Java SDK)

Phone Number Requirement

The MB WAY phone number is passed through:

payment_method_data.billing.phone

Field	Required	Format	Example
`payment_method_data.billing.phone`	Yes	E.164	`+351912345678`

If the phone number is missing, UseePay rejects the request:

billing.phone is required for mb_way

If the phone number is not in E.164 format, UseePay rejects the request:

billing.phone must be a valid E.164 phone number for mb_way

Response Example

When the payment has been initiated and UseePay is waiting for customer authorization, the PaymentIntent returns:

{
  "id": "1012611020000000002",
  "code": "0000",
  "message": "Approved or completed successfully",
  "amount": 1000,
  "currency": "EUR",
  "status": "requires_customer_action",
  "confirm": true,
  "orderType": "sale",
  "mode": "payment",
  "sale": true,
  "merchant_no": "500000000000000",
  "app_id": "merchant.example.com",
  "merchant_order_id": "order_mb_way_001",
  "refunded_amount": 0,
  "next_action": {
    "type": "mb_way_await_authorization",
    "mb_way_await_authorization": {}
  },
  "return_url": "https://merchant.example.com/payment/return",
  "auto_capture": true,
  "payment_attempt": {
    "billing": {
      "phone": "+351912345678",
      "address": {
        "country": "PT"
      }
    },
    "payment_method_details": {
      "type": "mb_way"
    }
  }
}

Handling `mb_way_await_authorization`

When the response contains:

{
  "next_action": {
    "type": "mb_way_await_authorization",
    "mb_way_await_authorization": {}
  }
}

the merchant should:

Inform the customer that an authorization request has been sent to the MB WAY app.

Ask the customer to open the MB WAY app.

Ask the customer to review and approve the payment.

Keep the payment result page in a waiting state.

Wait for the PaymentIntent status update or webhook notification.

Suggested customer message:

A payment authorization request has been sent to your MB WAY app.
Open the app and approve the payment to continue.

Do not redirect the customer to a URL because mb_way_await_authorization does not contain next_action.redirect.

Do not treat requires_customer_action as a successful payment.

Handling the Payment Result

Possible statuses include:

Status	Description	Merchant Action
`requires_customer_action`	Waiting for authorization in the MB WAY app	Display authorization instructions
`pending`	The payment is pending the final result from the payment provider	Wait for the webhook notification
`succeeded`	Payment completed successfully	Fulfill the order
`failed`	Payment failed or authorization was rejected	Display the failure and allow retry
`canceled`	Payment was canceled or expired	Close or recreate the payment

Always use the PaymentIntent status or webhook event as the source of truth. Do not fulfill the order based only on the initial API response.

Overview#

Payment Flow#

Notes#

Integration Guide#

Create and Confirm a PaymentIntent#

Request Example#

Request Example (Java SDK)#

Phone Number Requirement#

Response Example#

Handling mb_way_await_authorization#

Handling the Payment Result#