MB WAY

Receba pagamentos com MB WAY usando o endpoint unificado da LeonaPay.

Visão geral

Use POST /api/v2/payments com method: MBWAY. O valor deve ser positivo e a moeda deve corresponder ao mercado.

Campo	Valor
`Método`	`MBWAY`
`Mercado`	`Portugal`
`Moedas`	`EUR`
`Confirmação`	`Síncrona ou por webhook`

Criar pagamento MB WAY

Envie uma referência única do seu pedido. Campos específicos do método aparecem abaixo.

O cliente aprova o pedido no aplicativo MB WAY. Prazo conforme configuração comercial: a liberação do saldo segue a regra de dias corridos definida por empresa e método e registrada nas novas transações.

curl --request POST \
+  --url https://api.leonapay.com.br/api/v2/payments \
+  --header 'Accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --header 'x-api-key: {your_api_key}' \
+  --header 'idempotency-key: {unique_uuid_per_payment}' \
  --data '{
  "method": "MBWAY",
  "amount": 125.90,
  "currency": "EUR",
  "reference": "pedido-123",
  "payer": { "name": "Ana Silva", "phone": "+351912345678" },
  "expiresIn": 300
}'

Como simular o resultado no Sandbox

Crie o pagamento usando a chave e a Base URL do Sandbox. PIX, boleto, SPEI, MB WAY, transferências bancárias, PSE, Nequi e Bre-B permanecem aguardando até você enviar o resultado desejado ao endpoint de simulação. Use o ID retornado na criação do pagamento.

Troque PAID por FAILED ou EXPIRED para testar os outros cenários. A simulação aceita somente pagamentos da mesma empresa e do ambiente Sandbox.

Status	Resultado simulado
`PAID`	`Pagamento confirmado e webhook payment.paid emitido`
`FAILED`	`Pagamento recusado e webhook payment.failed emitido`
`EXPIRED`	`Cobrança expirada e webhook payment.expired emitido`

curl --request POST \
  --url https://sandbox.api.leonapay.com.br/api/v2/simulations/payments/{paymentId} \
  --header 'x-api-key: {sandbox_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{"status":"PAID"}'

Erros e retentativas de MB WAY

Toda falha inclui error.code, error.retryable, error.requestId e um link direto para a referência. Corrija erros ONP400 antes de criar uma nova tentativa. Para ONP502, ONP503 ou ONP429, repita exatamente a mesma requisição com a mesma chave de idempotência após retryAfter.

No painel, Integrações → Logs da API · 24h mostra a resposta pública e a tratativa pelo requestId, sem expor a liquidante usada.

Código	Interpretação	Ação
`ONP400_*`	`Campo, moeda ou regra do método inválida`	`Corrigir o campo indicado em error.field`
`ONP422_MBWAY_REJECTED`	`Operação recusada de forma definitiva`	`Revisar os dados e criar nova tentativa`
`ONP502_MBWAY_INVALID_RESPONSE`	`Instruções de pagamento incompletas`	`Retentar com a mesma idempotência`
`ONP503_MBWAY_TEMPORARILY_UNAVAILABLE`	`Método temporariamente indisponível`	`Backoff com jitter e mesma idempotência`

Resposta

Uma criação aceita retorna HTTP 201. O status inicial pode ser ACTION_REQUIRED, PENDING, AUTHORIZED ou PAID.

{
  "success": true,
  "onpayCode": "ONP201",
  "onpayDescription": "Payment created",
  "data": {
    "id": "pay_01J5VX8M8W8W6Q",
    "reference": "pedido-123",
    "status": "PENDING",
    "method": "MBWAY",
    "currency": "EUR",
    "amount": 125.90,
    "fee": 1.75,
    "customer": {
      "id": "cus_01J5VY2Q8G4K9D",
      "name": "Ana Souza",
      "email": null,
      "phone": null,
      "taxId": "12345678909"
    },
    "authorizationStatus": "PENDING",
    "expiresAt": "2026-08-20T18:05:00Z",
    "paidAt": null,
    "createdAt": "2026-08-25T01:04:23.295Z",
    "updatedAt": "2026-08-25T01:04:24.738Z"
  }
}

Ciclo da transação

Não conclua o pedido apenas pelo retorno do navegador. Consulte a API ou espere o evento assinado payment.paid.

Status	Descrição
`ACTION_REQUIRED`	`Aguardando confirmação ou autenticação 3DS`
`PENDING`	`Aguardando ação ou confirmação`
`AUTHORIZED`	`Autorizado, aguardando conclusão`
`PAID`	`Pagamento confirmado`
`FAILED`	`Falha no processamento`
`EXPIRED`	`Prazo encerrado`
`REFUNDED`	`Valor estornado`