Boleto

Receba pagamentos com Boleto usando o endpoint unificado da LeonaPay.

Visão geral

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

Campo	Valor
`Método`	`BOLETO`
`Mercado`	`Brasil`
`Moedas`	`BRL`
`Confirmação`	`Síncrona ou por webhook`

Criar pagamento Boleto

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

Exiba a linha digitável ou o PDF ao pagador. O boleto nasce PENDING e só deve ser considerado liquidado após payment.paid.

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": "BOLETO",
  "amount": 125.90,
  "currency": "BRL",
  "reference": "pedido-123",
  "dueDate": "2026-09-05",
  "payer": {
    "name": "Ana Souza",
    "taxId": "12345678909",
    "email": "ana@exemplo.com",
    "phone": "+5511999999999",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Conjunto 12",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310100",
      "country": "BR"
    }
  }
}'

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"}'

Dados obrigatórios do pagador

Colete os dados do pagador no seu checkout antes de chamar a API. Eles identificam a pessoa ou empresa que pagará o boleto. Não use automaticamente os dados da empresa que receberá o pagamento. Envie tudo dentro de payer na mesma requisição que cria o boleto.

Se qualquer campo obrigatório estiver ausente, a API retorna HTTP 400 com ONP400_BOLETO e informa os campos que precisam ser corrigidos. Não retente a mesma requisição sem corrigir os dados.

Campo	Obrigatório	Formato
`payer.name`	`Sim`	`Nome completo ou razão social`
`payer.taxId`	`Sim`	`CPF com 11 dígitos ou CNPJ com 14 dígitos`
`payer.email`	`Sim`	`E-mail válido do pagador`
`payer.phone`	`Não`	`Telefone com DDI e DDD`
`payer.address.street`	`Sim`	`Logradouro`
`payer.address.number`	`Sim`	`Número do endereço`
`payer.address.complement`	`Não`	`Complemento`
`payer.address.district`	`Sim`	`Bairro`
`payer.address.city`	`Sim`	`Cidade`
`payer.address.state`	`Sim`	`UF com 2 letras`
`payer.address.postalCode`	`Sim`	`CEP com 8 dígitos`
`payer.address.country`	`Não`	`BR quando omitido`
`dueDate`	`Sim`	`YYYY-MM-DD; hoje ou uma data futura`

Quando solicitar esses dados

Mostre o formulário do pagador quando ele escolher boleto no seu checkout. Depois que o formulário estiver válido, o seu backend envia valor, vencimento e payer juntos para POST /api/v2/payments. Uma resposta 201 devolve a linha digitável e o PDF; o pagamento continua PENDING até a confirmação por webhook.

Etapa	Responsabilidade
`1. Escolha do método`	`Exibir o formulário do pagador ao selecionar boleto`
`2. Validação`	`Validar CPF/CNPJ, e-mail, CEP e endereço antes do envio`
`3. Criação`	`Backend envia amount, dueDate e payer na mesma requisição`
`4. Exibição`	`Frontend mostra digitableLine ou pdfUrl ao pagador`
`5. Confirmação`	`Backend aguarda payment.paid antes de liberar o pedido`

Taxas do boleto

A taxa é calculada e gravada no momento da emissão. A API aplica, nesta ordem: configuração da empresa para BOLETO, taxa geral da empresa, configuração global para BOLETO e taxa global geral.

Alterar a configuração não recalcula boletos já emitidos.

Simular o ciclo no Sandbox

Boletos de Sandbox permanecem PENDING até a simulação. O mesmo fluxo atende PIX, SPEI, MB WAY e todos os outros métodos sem cartão, permitindo testar pagamento, falha, expiração, webhook e atualização do painel sem movimentar valores.

O simulador aceita pagamentos PENDING ou ACTION_REQUIRED pertencentes à mesma empresa da chave Sandbox.

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"}'

# Também aceitos: FAILED e EXPIRED

Erros e retentativas de Boleto

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_BOLETO_REJECTED`	`Operação recusada de forma definitiva`	`Revisar os dados e criar nova tentativa`
`ONP502_BOLETO_INVALID_RESPONSE`	`Instruções de pagamento incompletas`	`Retentar com a mesma idempotência`
`ONP503_BOLETO_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": "BOLETO",
    "currency": "BRL",
    "amount": 125.90,
    "fee": 1.75,
    "customer": {
      "id": "cus_01J5VY2Q8G4K9D",
      "name": "Ana Souza",
      "email": null,
      "phone": null,
      "taxId": "12345678909"
    },
    "barcode": "00193373700000012590000001000000000000000000",
    "digitableLine": "00190.00009 01000.000004 00000.000000 3 37370000001259",
    "documentNumber": "PAY01J5VX8M8W8W6Q",
    "dueDate": "2026-09-01",
    "beneficiary": "LeonaPay DIGITAL ORCHESTRATION S/A",
    "pdfUrl": "https://api.leonapay.com.br/api/v2/payments/pay_01J.../boleto",
    "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`