PIX

Receba pagamentos com PIX usando o endpoint unificado da LeonaPay.

Visão geral

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

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

Criar pagamento PIX

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

O campo qrCode contém o código PIX copia e cola. A confirmação definitiva do pagamento é enviada por webhook.

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": "PIX",
  "amount": 125.90,
  "currency": "BRL",
  "reference": "pedido-123",
  "payer": { "name": "Ana Souza", "taxId": "12345678909" },
  "expiresIn": 900
}'

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 PIX

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_PIX_REJECTED`	`Operação recusada de forma definitiva`	`Revisar os dados e criar nova tentativa`
`ONP502_PIX_INVALID_RESPONSE`	`Instruções de pagamento incompletas`	`Retentar com a mesma idempotência`
`ONP503_PIX_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": "PIX",
    "currency": "BRL",
    "amount": 125.90,
    "fee": 1.75,
    "customer": {
      "id": "cus_01J5VY2Q8G4K9D",
      "name": "Ana Souza",
      "email": null,
      "phone": null,
      "taxId": "12345678909"
    },
    "qrCode": "00020101021226880014br.gov.bcb.pix...",
    "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`