Pular para o conteúdo
LeonaPayDevelopers
Primeiros passosReferenciais da APIIntegraçõesv2
Respostas

Códigos de resposta

Use o status HTTP para a categoria do resultado e leonapayCode para o motivo específico.

Envelope de erro previsível

Toda falha transacional usa o mesmo contrato. leonapayCode é estável para automação; error.field aponta o campo; retryable informa se a mesma operação pode ser repetida; e requestId permite localizar o log exato nas últimas 24 horas. A liquidante é uma decisão interna da LeonaPay e não integra o contrato público.
{
  "success": false,
  "leonapayCode": "LP400_PAYER_TAX_ID",
  "leonapayDescription": "payer.taxId is required for PIX",
  "error": {
    "category": "VALIDATION",
    "leonapayCode": "LP400_PAYER_TAX_ID",
    "message": "payer.taxId is required for PIX",
    "field": "payer.taxId",
    "retryable": false,
    "requestId": "req_01J...",
    "docsUrl": "https://docs.leonapay.com.br/docs/errors#lp400-payer-tax-id"
  },
  "requestId": "req_01J..."
}

Status HTTP e decisão de retentativa

Use primeiro o HTTP para a categoria e depois leonapayCode para a causa. Nunca faça retentativa cega de um 4xx.
StatusSignificadoRetentar
200 / 201 / 202Operação aceita ou concluídaNão aplicável
400 / 413Payload, campo ou tamanho inválidoNão; corrija a requisição
401 / 403Credencial, permissão ou IP inválidoNão; corrija o acesso
404Recurso não encontrado no tenantNão
409Idempotência, saldo ou estado em conflitoSomente quando retryable=true
422Operação recusada após validaçãoNão; crie nova tentativa após corrigir
429Capacidade temporariamente limitadaSim; respeite Retry-After
502 / 503Serviço transacional temporariamente indisponívelSim; mesma idempotência e backoff
504Resultado ainda inconclusivoNão crie duplicata; consulte a operação original
500Falha inesperada da LeonaPayNão cegamente; use requestId

Diagnóstico por método

Cada método tem requisitos próprios, mas todos compartilham o mesmo envelope e a mesma política de retentativa.
MétodoValidação principalFalhas que exigem atenção
PIXBRL e payer.taxIdQR ausente/incompleto é transitório; rejeição cadastral não é
SPEIMXN e payer.taxIdCLABE ausente/incompleta é transitória; conta inválida não é
MB WAYEUR e payer.phone +351Timeout é transitório; telefone/rejeição no app não é
Crédito e débitoreturnUrl; paymentMethodToken é opcionalACTION_REQUIRED devolve sessionToken + checkoutUrl; consulte o status e warnings antes de considerar uma nova tentativa

Como investigar com requestId

A LeonaPay devolve o identificador no corpo e nos headers RequestId e x-request-id. No painel, abra Integrações → Logs da API · 24h, localize o registro pelo identificador exibido e veja a resposta pública e a tratativa recomendada. Nenhuma credencial ou resposta bruta da liquidante é exposta.
Guarde o requestId nos seus logs de aplicação. Não registre chaves de API, tokens de confirmação, PAN, CVV ou o corpo bruto de documentos.

Erro síncrono e falha assíncrona

Validações conhecidas pela LeonaPay retornam HTTP 400 antes do envio. Pagamentos e saques aceitos podem falhar depois: nesse caso, use GET /api/v2/transactions/{transactionId}, GET /api/v2/withdrawals/{withdrawalId} ou o webhook assinado. payment.failed e withdrawal.failed devolvem exatamente o mesmo data.error gravado na consulta.
Retente apenas quando retryable=true. Quando retryAfter existir, aguarde esse intervalo; preserve a mesma idempotência e consulte antes de criar uma nova operação.
LeonaPay Developers · API v2