MB WAY

MB WAY is Portugal's mobile wallet. The customer enters their phone number, gets a push notification on their MB WAY app, taps to authorise — funds settle the same day.

#Flow at a glance

text

1. POST /v1/payments  ──────▶  Neozentry QA returns transactionId
2. Customer enters their MB WAY phone number on your checkout
3. Neozentry QA pushes the request to the customer's MB WAY app (5-min window)
4. Customer taps "Pay" in their app
5. Webhook payment.completed arrives at your endpoint

#1. Create the payment

Endpoint POST /v1/payments

bash

curl -X POST https://qa.liqfy.com.br/v1/payments \
  -H "apikey: $QA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "currency": "EUR",
    "paymentMethods": ["MBWAY"],
    "customerName": "Ana Pereira",
    "customerEmail": "ana@example.com",
    "metadata": {
      "orderId": "ORD-2034",
      "phone": "+351912345678"
    },
    "idempotencyKey": "ORD-2034"
  }'

Field	Notes
`amount`	Cents. `4500` = € 45,00. MB WAY supports up to € 750 per transaction.
`currency`	Must be `"EUR"`.
`paymentMethods`	`["MBWAY"]`
`metadata.phone`	Portuguese mobile in E.164 (`+351XXXXXXXXX`). Required for MB WAY.

Response 201 Created

json

{
  "id": "c3d4e5f6-a7b8-4901-9cde-f01234567890",
  "status": "WAITING_PAYMENT",
  "amount": 4500,
  "currency": "EUR",
  "paymentMethods": ["MBWAY"],
  "createdAt": "2026-04-25T15:55:11.000Z"
}

The push to the customer's app is dispatched within seconds.

#2. Show a "waiting" screen

There's no QR code or redirect — the customer's phone is buzzing. Show them a loading state with a 5-minute countdown. Poll GET /v1/payments/{id} every 3 seconds for UX only:

const poll = async () => {
  const res = await fetch(`/api/payments/${txId}`); // server proxies to Neozentry QA
  const tx = await res.json();
  if (tx.status === 'PAID') return showSuccess();
  if (['REFUSED', 'EXPIRED', 'CANCELLED'].includes(tx.status)) return showFailure(tx.status);
  setTimeout(poll, 3000);
};
poll();

Backend fulfillment must still come from the webhook, never the poll.

#3. Confirm via webhook

json

{
  "event": "payment.completed",
  "data": {
    "transactionId": "c3d4e5f6-a7b8-4901-9cde-f01234567890",
    "amount": 4500,
    "status": "PAID",
    "previousStatus": "WAITING_PAYMENT",
    "paidWith": "MBWAY",
    "providerFee": 60,
    "platformFee": 45,
    "netAmount": 4395,
    "occurredAt": "2026-04-25T15:56:02.000Z"
  }
}

#Lifecycle

text

WAITING_PAYMENT  ──▶  PAID         ✓ fulfill order
                 ──▶  REFUSED      customer rejected on the app
                 ──▶  EXPIRED      no response within 5 minutes
                 ──▶  CANCELLED    customer hit Cancel

#Edge cases & FAQ

Q: The customer mistyped their phone number. A: The push is silently dropped and the charge expires after 5 minutes. Create a new transaction with the corrected number.

Q: Does the customer need a Portuguese bank account? A: Yes. MB WAY only works with Portuguese-issued cards/accounts.

Q: Can I retry the same transaction? A: No — once EXPIRED, the transaction is closed. Create a new one.

Q: What's the maximum amount? A: € 750 per transaction, € 2 500 per day per customer (MB WAY rules — these are not Neozentry QA limits).

Q: Customer says "Paid" but I have WAITING_PAYMENT for an hour. A: That's a Provider/MB WAY clearing-side delay. Contact qa@liqfy.com.br with the transaction id — we'll reconcile from the settlement file.

#Next

→ Multibanco · API Reference