MB WAY
MB WAY em EUR, com contrato público LeonaPay e confirmação assíncrona.
Limites e disponibilidade
Consulte
GET /api/v2/payment-methods antes de exibir o método. Use minAmount, maxAmount, settlement e available retornados para a empresa; os limites comerciais não são fixos na documentação.LP422_MBWAY_REJECTED é recusa definitiva: revise os dados e crie uma nova tentativa. Em LP502_MBWAY_INVALID_RESPONSE, LP503_MBWAY_TEMPORARILY_UNAVAILABLE ou LP429, repita a mesma requisição com a mesma idempotency-key após retryAfter, com backoff e jitter. Em timeout, consulte a operação antes de criar outra cobrança. Todo erro traz error.leonapayCode, error.retryable e error.requestId.
| Método | MBWAY |
|---|---|
Moeda | EUR |
Mercado | Portugal |
Limites de cash-in | EUR positivo, até duas casas decimais; sujeito aos limites comerciais da conta. Apenas entrada: não há saque MB WAY. Consulte MBWAY/EUR em GET /api/v2/payment-methods com a mesma credencial usada na criação. |
Tipo de instrução | PUSH |
Campos obrigatórios
Valide estes campos no seu backend antes de chamar a API. Não envie credenciais LeonaPay ao navegador.
| payer.phone | Telefone português no formato +351 seguido de 9 dígitos; recebe o pedido no aplicativo MB WAY |
|---|---|
payer.name | Nome do pagador (recomendado) |
amount | EUR positivo, até duas casas decimais |
expiresIn | Opcional: prazo do pedido em segundos, de 60 a 86400 |
Criar pagamento MB WAY
Envie
POST /api/v2/payments com uma chave idempotency-key UUID exclusiva.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","currency":"EUR","amount":125.90,"reference":"pedido-mbway-123","payer":{"name":"Ana Silva","phone":"+351912345678"},"expiresIn":300}'Resposta inicial completa
Persista
data.id, status, method, currency e todas as instruções retornadas.{"success":true,"leonapayCode":"LP201","data":{"id":"pay_01J...","reference":"pedido-mbway-123","status":"PENDING","method":"MBWAY","currency":"EUR","amount":125.90,"fee":2.50,"customer":{"id":"cus_01J...","name":"Ana Silva","email":null,"phone":"+351912345678","taxId":null},"authorizationStatus":"PENDING","expiresAt":"2026-11-04T18:05:00Z","paidAt":null,"createdAt":"2026-11-04T18:00:00Z","updatedAt":"2026-11-04T18:00:00Z"}}Tempo das instruções
A criação envia um pedido de pagamento ao telefone em payer.phone; o pagador aprova no aplicativo MB WAY. O status fica PENDING ou ACTION_REQUIRED até a confirmação; a aprovação no aplicativo aparece em authorizationStatus (por exemplo PENDING ou AUTHORIZED), e expiresAt é o prazo para aprovar; se vier nextAction.type=PUSH_CONFIRMATION, exiba o telefone e o prazo ao pagador. Não há QR Code nem link: não gere outra cobrança para reenviar o pedido.
Estados e webhook
A resposta inicial não comprova liquidação. Valide a assinatura HMAC (timestamp, ID do evento e corpo bruto), responda 2xx rapidamente e processe cada
event.id uma única vez.| Status | Ação |
|---|---|
PENDING | Aguardar instrução ou confirmação |
ACTION_REQUIRED | Entregar a ação ao pagador |
PAID | Liberar o pedido uma única vez |
FAILED | Encerrar a tentativa |
EXPIRED | Não reutilizar a instrução |
REFUNDED | Registrar devolução/reversão |
{"id":"evt_01J...","event":"payment.paid","occurredAt":"2026-09-22T18:32:10Z","data":{"id":"pay_01J...","reference":"pedido-123","status":"PAID","method":"MBWAY","currency":"EUR","amount":125.9}}Conciliação
Somente payment.paid assinado ou a consulta autenticada de GET /api/v2/transactions/{id} confirmam o crédito. A aprovação no aplicativo e o retorno do navegador não substituem a confirmação. A liberação do saldo segue a regra de dias corridos definida por empresa e método e registrada nas novas transações. Verifique x-leonapay-signature (timestamp, ID do evento e corpo bruto) e deduplique pelo ID do evento.
Erros e retentativas
Corrija respostas
LP400 antes de uma nova tentativa. Em LP429, LP502 ou LP503, use backoff com jitter e repita a mesma requisição com a mesma idempotência. Consulte o pagamento antes de criar outro.| Código | Ação |
|---|---|
LP400_* | Corrigir o campo indicado |
LP409_IDEMPOTENCY_CONFLICT | Não reutilizar UUID com conteúdo diferente |
LP422_MBWAY_REJECTED | Revisar os dados e iniciar nova tentativa |
LP503_MBWAY_TEMPORARILY_UNAVAILABLE | Retentar com a mesma idempotência |
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"}'