MB WAY — Portugal

MB WAY is a premier mobile wallet payment solution in Portugal. It allows customers to authorize transactions directly through their mobile banking application using a registered phone number. This method provides instant confirmation via push notifications and maintains high security by not sharing sensitive financial details during the transaction.

Requirements

Complete the following steps before integrating MB WAY:

• Authentication: Generate an access token using the Authentication endpoint.
• App Readiness: Ensure the customer has the MB WAY application installed and a phone number successfully registered with the service.
• Activation: Contact your Account Manager to validate eligibility and activate this payment method for your account.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. MBWay is only available in Portugal and only for EUR currency. To know more about the specific requirements of Portugal, be sure to review the resources below before you go live:

• Currency codes
• Document types
• Local taxes and regulations

Characteristics

Available Features

Integration Flow

Implement the MB WAY flow by collecting customer data on your frontend and handling the asynchronous authorization result from the MB WAY app.

1. Create the Payment Request

Call the Create – Authorize endpoint using the attributes defined below. Ensure all transaction data is nested within the data object.

Request Example:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --data '{
    "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
    "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
    "data": {
        "amount": 1200,
        "payment": {
            "payment_id": "e9595164-deaa-4341-bb37-b4b9c570a6d3",
            "payment_method": "MBWAY"
        },
        "currency": "EUR",
        "order": {
            "order_id": "ORDER_12345678901234567890123456",
            "sales_tax": 0,
            "product_type": "physical"
        },
        "customer": {
            "phone_number": "351#910000000",
            "email": "[email protected]"
        }
    }
}'

2. Handle the Customer Approval

Once the request is submitted, the following sequence occurs:

1. Notification: The customer receives a push notification on their mobile device.
2. Authorization: The customer opens the MB WAY app to review and authorize the payment.
3. Final Status:
   • Approved: Status updates to APPROVED.
   • Declined/Timed Out: Status updates to CANCELED.

Post-Sale Operations

Refunds and Cancellations

MB WAY supports flexible post-sale management for both settled and unsettled transactions.

• Cancellations: Performed on the same day as the transaction before the daily cutoff. Partial cancellations are supported.
• Refunds: Performed after transaction settlement. Both full and partial refunds are supported, and you may execute multiple refunds against a single transaction.

To process a refund or cancellation, follow the instructions in the Refund a Payment guide.

Read more

• Review Authentication for token management and security best practices.

MBWay Payments

MBWay is a mobile wallet payment solution widely used in Portugal, created by SIBS. It allows customers to authorise payments directly from their mobile banking app using their phone number, delivering instant confirmation through push notifications without exposing card details. The Global API supports MBWay as a wallet payment method.

This guide provides instructions for integrating MBWay payments, including request examples, push notification handling, and webhook processing.

Requirements

Before integrating MBWay you need to:

• Generate an access token through the Authentication endpoint.
• Configure a public HTTPS callback_url that receives status updates when customers approve or decline payments in their MBWay app.
• Ensure customers have the MBWay app installed and their phone number registered with MBWay.

To enable MBWay you must work with your Account Manager, who validates eligibility and activates the payment method.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. MBWay is only available in Portugal and only for EUR currency. To know more about the specific requirements of Portugal, be sure to review the resources below before you go live:

• Currency codes
• Document types
• Local taxes and regulations

You can also use test cards to simulate specific scenarios.

Characteristics

The table below summarizes the shared behavior and requirements for MBWay payments.

After you create the payment request, a push notification is sent to the customer’s device. The customer opens their MBWay app to approve or decline the payment. Status updates are delivered via webhooks to your callback_url.

Available features

Use the matrix below to confirm the scenarios currently supported for MBWay.

Payment flow

This section guides you through the complete process of implementing MBWay payments, from collecting customer information to handling the payment response and webhook notifications. The diagram below provides an overview of a payment with Mbway:

1. Create the payment request

As this is a direct payment flow, you must first implement a payment form on your frontend to collect the necessary customer information. Once collected, call the Create – Authorize endpoint with the attributes below.

The table outlines the minimum fields required for an MBWay payment.

Phone number format: Use countryCode#phoneNumber (e.g., 351#912345678). Do not include +, spaces, or dashes. Country code: 1-4 digits. Phone number: 6-15 digits.

The following sample request shows how to initialize an MBWay payment.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "{{$randomUUID}}",
  "request_id": "{{$guid}}",
  "order_id": "{{order_id_mb}}",
  "data": {
    "amount": 5000,
    "currency": "EUR",
    "payment": {
      "payment_method": "WALLET",
      "brand": "MBWAY"
    },
    "additional_data": {
      "customer": {
        "phone_number": "55#11980585984",
        "billing_address": {
          "district": "B",
          "city": "City Z",
          "state": "SP",
          "country": "PT",
          "postal_code": "05781000",
          "complement": "N/A"
        }
      },
      "shippings": {
        "address": {
          "street": "R a",
          "number": "1",
          "district": "B",
          "city": "City Z",
          "state": "SP",
          "country": "PT",
          "postal_code": "05781000",
          "complement": "N/A"
        }
      }
    }
  }
}

The API responds with a payload similar to the example below.

{
  "idempotency_key": "5befb59b-85be-46cd-b924-ec77f5b75d5c",
  "seller_id": "2ee453aa-3ab6-447b-becf-d9d4360051eb",
  "payment_id": "32f5b40-466c-4640-ad32-5a62f7dd0173",
  "order_id": "lrzrlxc4y04lnuddhioerpcz442wu0g4",
  "amount": "5000",
  "currency": "EUR",
  "status": "WAITING",
  "received_at": "2026-04-15T17:52:55.422Z",
  "transaction_id": "lrzrlxc4y04lnuddhioerpcz442wu0g4",
  "reason_code": "00",
  "reason_message": "Pending",
  "acquirer_transaction_id": "s23iDV9z9GUwpS11Hm9j"
}

2. Customer approval flow

After the API call, the following sequence occurs:

1. Push Notification: A notification is sent to the customer’s mobile device (typically within 1-5 seconds).
2. MBWay App: The customer opens their MBWay app and sees the payment request details.
3. Customer Action:
   • Approves payment → Status becomes APPROVED (webhook sent)
   • Declines payment → Status becomes DECLINED (webhook sent)
   • No action (timeout after 5-10 minutes) → Status becomes DECLINED (webhook sent)

3. Verify payment status

When the customer approves the payment in their MBWay app, a webhook notification is sent with the updated payment status. You can also periodically check the payment status using the Get Transaction endpoint.

Refunds and cancellations

MBWay payments support both cancellations and refunds:

• Cancellations: Available for same-day transactions before the daily cutoff time. Only full cancellations are supported (no partial cancellations).
• Refunds: Available for transactions after settlement. Both full and partial refunds are supported, and multiple refunds are allowed.

To process a refund or cancellation, follow the instructions in the Refund a Payment guide.

For detailed information about refund timing, cutoff times, and country-specific availability, refer to the Core Cards reference.

Read more

• Review Authentication for token management and security best practices.