MB WAY Payments

Accept payments through MB WAY, Europe's leading mobile wallet. The buyer links their phone number to their cards in the MB WAY app. Your integration submits a single Web Checkout API request. The buyer then confirms the payment on their own phone with biometrics or PIN, with no card entry and no 3DS.

This guide shows you how to create a payment intent and submit the MB WAY payment with the buyer's phone number. It also shows you how to resolve the final status asynchronously.

This document applies to the following country:

Europe

How it works

Use MB WAY when you want to offer the leading mobile payment method in Europe. Buyers approve in the app with biometrics or PIN and don't type card details. Key characteristics:

  • No card entry: the buyer pays with the cards already linked to their phone number in the MB WAY app.
  • In-app confirmation: the buyer receives a push notification in the MB WAY app and approves with biometrics or PIN.
  • Asynchronous processing: submitting the payment does not return the final result. The payment stays in PENDING and resolves when the buyer confirms on their phone. You get the final status through a webhook.

The end-to-end flow involves the buyer, your frontend, your backend, and the Getnet Web Checkout API:

Before you start

Make sure the following are in place before you integrate:

  • The seller (x-seller-id) has MB WAY enabled (mbway.enabled).
  • Your checkout collects the buyer's mobile phone number, which is required to send the push to the MB WAY app.
  • You have generated your token by following the Authentication document.

Step 1: Create the payment intent

Call the Web Checkout API to create a payment intent. It returns a payment_intent_id and a redirect_url.
Endpoint
POST /payment-intent
Required fields
FieldTypeDescriptionExample
payment.currencyStringCurrency code.EUR
payment.amountIntegerPurchase amount in integer format, where the last 2 digits represent the cents. For countries where cents do not apply, fill in the amount with 2 zeros to the right.5000
customer.phone_numberstringRequired for MB WAY — mobile number that receives the push.351#912345678
customer.customer_idStringWe recommend using the customer's document number. Use only letters and numbers, without special characters, separators or spaces.12345678912
customer.nameStringCustomer's full name.John Doe Smith
customer.emailStringCustomer's email address.customer@email.com.br
customer.billing_address.streetStringName of a street.Calle Gran Via
customer.billing_address.numberStringNumber that identifies the position of a building on a street.1000
customer.billing_address.countryStringCountry code.PT
customer.billing_address.postal_codeStringPostal or ZIP code.90230060
Optional fields
FieldTypeDescriptionExample
configurations.3dsbooleanControls 3D Secure authentication.true or false
configurations.preauthorizationbooleanIndicates if the payment is a pre-authorization.true or false
configurations.card_verificationbooleanIndicates if this is a card verification flow. Does not apply to Bizum.true or false
configurations.success_urlstringRedirect URL in case of successful payment.https://www.mystore.com/checkout/success
configurations.error_urlstringRedirect URL in case of an error during payment.https://www.mystore.com/checkout/error
soft_descriptorstringPayment description that appears on the customer's receipt.Tienda ES
expires_atstringPayment intent expiration.3d4h15m
information icon
phone_number: You send the phone number together with the customer's details when you create the payment intent. However, the push goes to the number the customer enters at purchase, after selecting the payment method. If the two numbers differ, we always use the one the customer enters at payment time.

Example request

The following request creates a payment intent for an MB WAY wallet payment.

JSON
{ "idempotency_key": "5befb59b-85be-46cd-b924-ec77f5b75d5c", "request_id": "8a2c1f40-4e4e-4a3e-9f21-6e4b9d7d1234", "order_id": "ORDER-MBWAY-0001", "data": { "amount": 5000, "currency": "EUR", "payment": { "payment_method": "WALLET", "brand": "MBWAY" }, "additional_data": { "customer": { "name": "João Silva", "phone_number": "351#912345678", "email": "joao.silva@example.com", "billing_address": { "street": "Rua Augusta", "number": "100", "district": "Baixa", "city": "Lisboa", "state": "Lisboa", "country": "PT", "postal_code": "1100-053", "complement": "Apto 2" } }, "shippings": { "address": { "street": "Rua Augusta", "number": "100", "district": "Baixa", "city": "Lisboa", "state": "Lisboa", "country": "PT", "postal_code": "1100-053", "complement": "Apto 2" } } } } }

Example response — pending/waiting

The following response shows a payment that is waiting for the buyer's approval.

JSON
{ "idempotency_key": "5befb59b-85be-46cd-b924-ec77f5b75d5c", "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "payment_id": "32f5b40-466c-4640-ad32-5a62f7dd0173", "order_id": "ORDER-MBWAY-0001", "amount": "5000", "currency": "EUR", "status": "WAITING", "received_at": "2026-08-25T20:30:00.422Z", "transaction_id": "ORDER-MBWAY-0001", "reason_code": "00", "reason_message": "Pending", "acquirer_transaction_id": "acq-mbway-123456" }

For MB WAY, the asynchronous result is one of the following statuses:

  • PENDING/WAITING: waiting for the customer to approve in the MB WAY app.
  • APPROVED: the customer approved and the payment was confirmed.
  • DECLINED: the customer declined or the transaction was refused.

Step 2: Submit the MB WAY payment

Submit the payment with the MB WAY method and the buyer's phone number. This step bypasses validate-session and 3DS. The backend generates the MB WAY request at the provider. The buyer then receives a push notification in the MB WAY app to approve the payment.

Step 3: Confirm the result

MB WAY is asynchronous: submitting the payment doesn't return the final result. The payment stays in PENDING/WAITING until the buyer confirms in the app. Resolve the final status in one of two ways:

  • Webhook: receive the approved or denied notification (see payloads below).

Example response — approved

The following webhook payload shows an approved payment.

JSON
{ "payment_intent_id": "ee0b7dd5-92da-4ef4-ad3b-0ba369ad0efe", "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537", "order_id": "ORDER_MBWAY_PT_0001", "mode": "instant", "seller": { "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b", "trade_name": "GetNet Shop", "merchant_document": "00000000000", "settings": { "notification_url_configured": true } }, "customer": { "customer_id": "customer_pt_005", "name": "Jose Silva", "email": "customer@email.com", "document_type": "nif", "document_number": "250000000" }, "payment": { "method": "mbway", "amount": 5000, "currency": "EUR", "result": { "payment_id": "32f5b40-466c-4640-ad32-5a62f7dd0173", "status": "APPROVED", "authorization_code": "999999", "transaction_datetime": "2026-07-08T12:00:00.000Z" } }, "created_at": "2026-07-08T11:58:00.000Z", "updated_at": "2026-07-08T12:00:00.000Z" }

Example response — denied

The following webhook payload shows a denied payment.

JSON
{ "payment_intent_id": "ee0b7dd5-92da-4ef4-ad3b-0ba369ad0efe", "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537", "order_id": "ORDER_MBWAY_PT_0001", "mode": "instant", "payment": { "method": "mbway", "amount": 5000, "currency": "EUR", "result": { "payment_id": "32f5b40-466c-4640-ad32-5a62f7dd0173", "status": "DECLINED", "transaction_datetime": "2026-07-08T12:05:00.000Z", "return_message": "Payment rejected or expired in MB WAY app" } }, "created_at": "2026-07-08T11:58:00.000Z", "updated_at": "2026-07-08T12:05:00.000Z" }

On this page

MB WAY Payments