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

1. POST /v1/payments  ──────▶  a Moonip devolve o transactionId
2. O cliente informa o número de celular do MB WAY no seu checkout
3. A Moonip 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 charge.paid chega no seu endpoint

#1. Criar a cobrança

Endpoint POST /v1/payments

curl -X POST https://api.moonip.io/v1/payments \
  -H "Authorization: Bearer $MOONIP_API_KEY" \
  -H "Idempotency-Key: ORD-2034" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500,
    "currency": "EUR",
    "paymentMethods": ["MBWAY"],
    "customerName": "Ana Pereira",
    "customerEmail": "ana@example.com",
    "customerPhone": "+351912345678",
    "metadata": { "orderId": "ORD-2034" }
  }'

Idempotência. O POST /v1/payments aceita o cabeçalho Idempotency-Key (preferido) ou o campo de corpo idempotencyKey como alternativa quando o cabeçalho está ausente; envie pelo menos um. Se enviar os dois, eles precisam ser iguais — valores divergentes são 400, e nenhum dos dois também é 400 nesta rota.

Resposta 201 Created

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

Com o SDK oficial (o mesmo pacote neutro para qualquer marca — configure-o com https://api.moonip.io):

Envie o customerPhone no input — o SDK repassa o campo de wire customerPhone.

#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 Moonip
  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

{
  "id": "evt_00000000000000000000000000000001",
  "object": "event",
  "api_version": "2026-07-23",
  "type": "charge.paid",
  "created_at": "2026-04-25T15:56:02.000Z",
  "data": {
    "object": {
      "id": "ch_c3d4e5f6-a7b8-4901-9cde-f01234567890",
      "object": "charge",
      "status": "paid",
      "amount": 4500,
      "currency": "EUR",
      "payment_method": "mbway",
      "settlement": {}
    }
  }
}

#Ciclo de vida

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 Moonip).

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@moonip.io com o id da transação — nós conciliamos pelo arquivo de liquidação.

#Próximo

→ Multibanco · Referência da API