MB WAY

O MB WAY é a carteira móvel de Portugal. O cliente informa o número de celular, recebe uma notificação push no app MB WAY e toca para autorizar — o dinheiro liquida no mesmo dia.

#O fluxo, de relance

text

1. POST /v1/payments  ──────▶  a I4Tpay devolve o transactionId
2. O cliente informa o número de celular do MB WAY no seu checkout
3. A I4Tpay envia o pedido por push para o app MB WAY do cliente (janela de 5 min)
4. O cliente toca em "Pagar" no app
5. O webhook payment.completed chega no seu endpoint

#1. Criar a cobrança

Endpoint POST /v1/payments

bash

curl -X POST https://i4tpay.beta.zentry.cloud/v1/payments \
  -H "apikey: $I4TPAY_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"
  }'

Campo	Observação
`amount`	Centavos. `4500` = € 45,00. O MB WAY aceita até € 750 por transação.
`currency`	Precisa ser `"EUR"`.
`paymentMethods`	`["MBWAY"]`
`metadata.phone`	Celular português em E.164 (`+351XXXXXXXXX`). Obrigatório no MB WAY.

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

O push para o app do cliente sai em poucos segundos.

#2. Mostrar uma tela de espera

Não há QR Code nem redirect — o celular do cliente está vibrando. Mostre um estado de carregamento com uma contagem regressiva de 5 minutos. Consulte GET /v1/payments/{id} a cada 3 segundos só para a experiência na tela:

const poll = async () => {
  const res = await fetch(`/api/payments/${txId}`); // o seu servidor repassa para a I4Tpay
  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();

A liberação do pedido no backend continua vindo do webhook, nunca da consulta.

#3. Confirmar pelo 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"
  }
}

#Ciclo de vida

text

WAITING_PAYMENT  ──▶  PAID         ✓ libere o pedido
                 ──▶  REFUSED      o cliente recusou no app
                 ──▶  EXPIRED      sem resposta em 5 minutos
                 ──▶  CANCELLED    o cliente apertou Cancelar

#Casos de borda e dúvidas

P: O cliente digitou o número de celular errado. R: O push é descartado sem aviso e a cobrança expira depois de 5 minutos. Crie uma transação nova com o número correto.

P: O cliente precisa de conta em banco português? R: Sim. O MB WAY só funciona com cartões/contas emitidos em Portugal.

P: Posso tentar de novo a mesma transação? R: Não — depois de EXPIRED, a transação está encerrada. Crie uma nova.

P: Qual é o valor máximo? R: € 750 por transação e € 2 500 por dia por cliente (regras do MB WAY — não são limites da I4Tpay).

P: O cliente diz "Pago", mas para mim está WAITING_PAYMENT há uma hora. R: É um atraso do lado da compensação do provedor/MB WAY. Escreva para suporte@i4tpay.beta.zentry.cloud com o id da transação — nós conciliamos pelo arquivo de liquidação.

#Próximo

→ Multibanco · Referência da API