Mbway

MB WAY is an asynchronous mobile wallet payment solution widely used in Portugal and managed by SIBS. It allows customers to authorize payments directly through the MB WAY app using the phone number registered with their bank, without entering or exposing card details during checkout.

After the merchant creates the payment, MB WAY sends a push notification to the customer's mobile device. The customer opens the MB WAY app to approve or decline the payment.

This guide provides instructions for integrating MB WAY payments, including request examples, customer authorization, expiration handling, webhook processing, status verification, cancellations, and refunds.

information icon
Important: MB WAY is asynchronous. The initial API response returns WAITING, which means that the payment request was created successfully and is awaiting customer authorization. The MB WAY notification expires 4 minutes and 30 seconds after the payment intent is created. The final payment status is received through a webhook or by polling the Get Transaction endpoint.

Requirements

Before integrating MB WAY you need to:

  • Generate an access token through the Authentication endpoint.
  • Make sure your seller account is enabled for MB WAY.
  • Collect the customer's MB WAY-enabled phone number during checkout.
  • Implement webhook event handling or payment status polling.
  • Ensure your integration does not fulfill the order while the payment status is WAITING.
information icon

To enable MB WAY you must work with your Account Manager, who validates eligibility and activates the payment method for your seller account.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. MB WAY is only available in Portugal and only supports EUR currency.

To learn more about the specific requirements for Portugal, review the resources below before going live:

Characteristics

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

CapabilityDetails
Integration typeAsynchronous mobile wallet payment with no external browser redirect
Customer interactionPush notification sent to the customer's mobile device through the MB WAY app
Credentials requiredCustomer's MB WAY-enabled phone number in countryCode#phoneNumber format
Initial statusThe initial API response returns WAITING while the payment awaits customer authorization
ConfirmationAsynchronous: the customer approves or declines the payment through the MB WAY app
Authorization timeThe MB WAY payment notification expires 4 minutes and 30 seconds after the payment intent is created
Refund periodRefunds can be requested for up to 15 months from the original payment date
NotificationsWebhooks or status polling can be used to track asynchronous payment status updates
CurrencyEUR only
Country availabilityPortugal only

After you create the payment request, a push notification is sent to the customer's device. The customer opens the MB WAY app to approve or decline the payment. Status updates are delivered asynchronously through webhooks or can be retrieved using the Get Transaction endpoint.

Available features

Use the matrix below to confirm the scenarios currently supported for MB WAY.

Payment flowSupported countriesPurchasesRefundsPartial refundsMultiple refundsPre-authorizations
WalletPortugal✅✅✅✅❌

Payment flow

This section guides you through the complete process of implementing MB WAY payments, from collecting the customer's phone number to handling the payment response, expiration, and webhook notifications.

The diagram below provides an overview of an MB WAY payment:

1. Create the payment request

As MB WAY uses an asynchronous wallet payment flow, you must first implement a payment form on your frontend to collect the customer's MB WAY-enabled phone number.

Once collected, call the Create – Authorize endpoint with the attributes below.

The table outlines the minimum fields required for an MB WAY payment.

AttributeDescriptionRequired value
idempotency_keyUnique identifier used to prevent duplicate processingUUID
request_idUnique identifier used to trace the requestUUID
order_idMerchant reference used for reconciliationUnique string. Must be unique and have a maximum of 35 characters.
data.amountTransaction amount in centsInteger, for example 5000 for €50.00
data.currencyISO 4217 currency codeEUR
data.payment.payment_methodWallet payment methodWALLET
data.payment.brandMB WAY brand identifierMBWAY
data.additional_data.customer.phone_numberCustomer's MB WAY-enabled phone numbercountryCode#phoneNumber
information icon
Phone number format: Use countryCode#phoneNumber, for example 351#912345678. Do not include the + symbol, spaces, parentheses, or hyphens. The country code must contain between 1 and 4 digits, and the phone number must contain between 6 and 15 digits.

Valid example:

text
351#912345678

Invalid examples:

text
+351912345678 351 912 345 678 351-912345678 351#912-345-678

The following sample request shows how to initialize an MB WAY payment using only the minimum required customer information.

bash
curl --request POST \ --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \ --header 'Authorization: Bearer <your-token>' \ --header 'Content-Type: application/json' \ --data '{ "idempotency_key": "5befb59b-85be-46cd-b924-ec77f5b75d5c", "request_id": "c4045e74-ef2e-4f8b-a30d-6ba63c57b407", "order_id": "MBWAY-20260415-00001", "data": { "amount": 5000, "currency": "EUR", "payment": { "payment_method": "WALLET", "brand": "MBWAY" }, "additional_data": { "customer": { "phone_number": "351#912345678" } } } }'

You can also include additional customer, billing, and shipping information when required by risk, compliance, fraud prevention, or local configuration.

bash
curl --request POST \ --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \ --header 'Authorization: Bearer <your-token>' \ --header 'Content-Type: application/json' \ --data '{ "idempotency_key": "5befb59b-85be-46cd-b924-ec77f5b75d5c", "request_id": "c4045e74-ef2e-4f8b-a30d-6ba63c57b407", "order_id": "MBWAY-20260415-00001", "data": { "amount": 5000, "currency": "EUR", "payment": { "payment_method": "WALLET", "brand": "MBWAY" }, "additional_data": { "customer": { "email": "customer@example.com", "document_number": "123456789", "document_type": "nif", "name": "Jose da Silva", "phone_number": "351#912345678", "billing_address": { "street": "Avenida da Liberdade", "number": "10", "complement": "2A", "district": "Santo Antonio", "city": "Lisbon", "state": "Lisbon", "country": "PT", "postal_code": "1250-096" } }, "shippings": { "address": { "street": "Avenida da Liberdade", "number": "10", "complement": "2A", "district": "Santo Antonio", "city": "Lisbon", "state": "Lisbon", "country": "PT", "postal_code": "1250-096" } } } } }'

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": "MBWAY-20260415-00001", "amount": "5000", "currency": "EUR", "status": "WAITING", "received_at": "2026-04-15T17:52:55.422Z", "transaction_id": "MBWAY-20260415-00001", "reason_code": "00", "reason_message": "Pending", "acquirer_transaction_id": "s23iDV9z9GUwpS11Hm9j" }

The table below describes the main response fields.

AttributeDescription
payment_idPayment identifier used to query the payment status and correlate asynchronous updates
order_idMerchant order reference used for reconciliation
amountTransaction amount in cents
currencyTransaction currency. For MB WAY, this value is EUR
statusCurrent payment status. The initial successful response returns WAITING
received_atDate and time when the payment request was received
transaction_idTransaction identifier associated with the payment
reason_codeProcessing reason code returned by the API
reason_messageHuman-readable description associated with the processing status
acquirer_transaction_idTransaction identifier assigned by the acquirer or payment provider
information icon
Use the status field to determine the payment lifecycle. Do not use reason_code alone to decide whether the order can be fulfilled.

2. Customer approval flow

After the API call, the following sequence occurs:

  1. Payment request: Getnet creates the payment and returns the initial WAITING status.
  2. Push notification: MB WAY sends a notification to the customer's registered mobile device.
  3. MB WAY app: The customer opens the MB WAY app and reviews the merchant and payment information.
  4. Customer action:
    • Approves payment → Status becomes APPROVED and an APPROVED_TRANSACTIONS webhook event is sent.
    • Declines or rejects payment → Status becomes DECLINED and a REJECTED_TRANSACTIONS webhook event is sent.
    • Does not respond within 4 minutes and 30 seconds → The notification expires and a REJECTED_TRANSACTIONS webhook event can be sent.
  5. Payment confirmation: Getnet receives the result and updates the payment status asynchronously.
  6. Order fulfillment: The merchant fulfills the order only after confirming the final APPROVED status.
information icon
The customer has 4 minutes and 30 seconds from the creation of the payment intent to authorize the payment. The countdown starts when the payment intent is successfully created, not when the customer opens the MB WAY app.

3. Handle payment expiration

The MB WAY payment notification expires 4 minutes and 30 seconds after the payment intent is created.

The customer must approve the payment through the MB WAY app within this period. After the notification expires, the customer can no longer use that payment request to complete the authorization.

If the payment is not completed within the authorization period:

  1. Do not fulfill the order.
  2. Wait for the final payment status through a webhook or query the Get Transaction endpoint.
  3. Create a new payment request if the customer wants to try again.
information icon
Important: Do not assume that the payment failed only because the checkout countdown ended. Always confirm the final transaction status through a webhook or the Get Transaction endpoint.

4. Verify payment status

When the customer approves, declines, or does not complete the payment, a webhook notification is sent with the updated payment status.

You can also check the payment status using the Get Transaction endpoint.

Use the payment_id returned in the initial response.
bash
curl --request GET \ --url https://api.pre.globalgetnet.com/dpm/hub-payment-info/v1/payments/info/{payment_id} \ --header 'Authorization: Bearer <your-token>'

Use status polling as a fallback when:

  • Webhook delivery is delayed.
  • The merchant does not receive a webhook.
  • The customer returns to the checkout before the final webhook is processed.
  • The merchant needs to reconcile an uncertain payment result.
information icon

Avoid excessive polling. Use an appropriate interval and stop polling after receiving a final payment status.

Webhooks

Use webhooks to receive asynchronous status updates for MB WAY payments. Webhooks are recommended for production integrations, while status polling should only be used as a fallback.

To learn how to configure and receive webhook notifications, see the Webhooks guide.

EventDescription
PENDING_TRANSACTIONSSent when the payment request is created and is awaiting customer authorization
APPROVED_TRANSACTIONSSent when the customer successfully approves the payment through the MB WAY app
REJECTED_TRANSACTIONSSent when the payment is declined, rejected, expires, or cannot be authorized
CANCELLED_TRANSACTIONSSent when the payment is cancelled before completion
information icon
Webhook events may be delivered more than once. Process each notification idempotently and use the payment_id to correlate the event with the original payment request.

Your webhook implementation should:

  • Validate the webhook according to the security mechanism described in the Webhooks guide.
  • Return a successful HTTP response after processing the event.
  • Support repeated delivery of the same event.
  • Process notifications idempotently.
  • Use payment_id or order_id to correlate the notification with the original payment.
  • Retrieve the transaction through the Get Transaction endpoint when the result is uncertain.

Status reference

The table below describes the expected status lifecycle for MB WAY payments and the corresponding webhook events.

StatusWebhook eventDescriptionNext action
WAITINGPENDING_TRANSACTIONSPayment request created successfully and awaiting customer authorizationAsk the customer to open the MB WAY app and await the webhook or poll the Get Transaction endpoint
APPROVEDAPPROVED_TRANSACTIONSCustomer approved the payment successfully through the MB WAY appFulfill the order and record the payment for reconciliation
DECLINEDREJECTED_TRANSACTIONSPayment was declined, rejected or expiredDo not fulfill the order.
CANCELLEDCANCELLED_TRANSACTIONSPayment was cancelled before completionRecord the cancellation and stop fulfillment
information icon
Treat only APPROVED as confirmation that the payment was successfully completed.

Refunds and cancellations

MB WAY payments support both cancellations and refunds:

  • Cancellations: Available for eligible same-day transactions before the applicable daily cutoff time. Only full cancellations are supported.
  • Refunds: Available for eligible transactions after settlement. Full refunds, partial refunds, and multiple refunds are supported.
  • Refund period: Refunds can be requested for up to 15 months from the original payment date.

The accumulated refunded amount must not exceed the original payment amount.

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

For detailed information about eligibility, settlement requirements, cutoff times, and country-specific availability, refer to the payment method availability reference.

Best practices

Follow these recommendations when implementing MB WAY:

  • Collect the phone number using the countryCode#phoneNumber format.
  • Validate the phone number format before sending the request.
  • Clearly instruct the customer to open the MB WAY app after the payment is created.
  • Keep the checkout page available while the payment is awaiting customer authorization.
  • Display a countdown based on the 4-minute-and-30-second authorization period.
  • Start the countdown when the payment intent is successfully created, not when the customer opens the MB WAY app.
  • Do not automatically classify the payment as declined when the checkout countdown ends.
  • Confirm the final status through a webhook or the Get Transaction endpoint.
  • Create a new payment request if the notification expires and the customer wants to retry.
  • Do not fulfill the order while the status is WAITING.
  • Use webhooks in production and status polling only as a fallback.
  • Process webhook events idempotently because the same notification may be delivered more than once.
  • Store payment_id, order_id, transaction_id, amount, and the final payment status for reconciliation.
  • Use a unique idempotency_key for every payment attempt.
  • Do not reuse an idempotency key with different request data.
  • Ensure refund workflows enforce the maximum period of 15 months from the original payment date.
  • Allow the customer to select another payment method when the payment is declined or cannot be completed.

Read more

On this page

Mbway&#x20;