Mbway

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

You can also use test cards to simulate specific scenarios.

Characteristics

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

Capability	Details
Customer interaction	Push notification sent to customer's mobile device via Mbway app
Credentials required	Customer's MBWay-enabled phone number in format `countryCode#phoneNumber`
Confirmation	Asynchronous: initial `PENDING` status, then `APPROVED` or `DECLINED` via webhook
Notifications	Webhooks for asynchronous status updates when customer approves/declines

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	Supported countries	Purchases	Refunds	Partial refunds	Multiple refunds	Pre-authorizations
Wallet	Portugal	✅	✅	✅	✅	❌

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.

Attribute	Description	Required value
`payment_method`	Wallet payment method	`WALLET`
`brand`	Mbway brand identifier	`MBWAY`
`callback_url`	Where status updates are sent	Your HTTPS endpoint
`amount`	Transaction amount in cents	Integer (e.g. `5000` for €50.00)
`currency`	ISO currency code	`EUR`
`order_id`	Merchant reference for reconciliation	Unique string
`customer.phone`	Customer's Mbway phone number (mandatory)	Format: `countryCode#phoneNumber`

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.

bash

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"
        }
      }
    }
  }
}'

bash

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.

json

{
  "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"
}

json

{
  "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:

Push Notification: A notification is sent to the customer's mobile device (typically within 1-5 seconds).
Mbway App: The customer opens their Mbway app and sees the payment request details.
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.