Pular para o conteúdo
LeonaPayDevelopers
Primeiros passosReferenciais da APIIntegraçõesv2
Portugal · EUR

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étodoMBWAY
MoedaEUR
MercadoPortugal
Limites de cash-inEUR 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çãoPUSH

Campos obrigatórios

Valide estes campos no seu backend antes de chamar a API. Não envie credenciais LeonaPay ao navegador.
payer.phoneTelefone português no formato +351 seguido de 9 dígitos; recebe o pedido no aplicativo MB WAY
payer.nameNome do pagador (recomendado)
amountEUR positivo, até duas casas decimais
expiresInOpcional: 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.
StatusAção
PENDINGAguardar instrução ou confirmação
ACTION_REQUIREDEntregar a ação ao pagador
PAIDLiberar o pedido uma única vez
FAILEDEncerrar a tentativa
EXPIREDNão reutilizar a instrução
REFUNDEDRegistrar 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ódigoAção
LP400_*Corrigir o campo indicado
LP409_IDEMPOTENCY_CONFLICTNão reutilizar UUID com conteúdo diferente
LP422_MBWAY_REJECTEDRevisar os dados e iniciar nova tentativa
LP503_MBWAY_TEMPORARILY_UNAVAILABLERetentar 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.
StatusResultado simulado
PAIDPagamento confirmado e webhook payment.paid emitido
FAILEDPagamento recusado e webhook payment.failed emitido
EXPIREDCobranç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"}'
LeonaPay Developers · API v2