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

Webhooks

Receba alterações de status em tempo real e confirme a autenticidade de cada evento.

Eventos disponíveis

Cadastre uma URL HTTPS no painel. Cada entrega é assinada e sua resposta fica registrada nos logs de endpoints. Saques em OUTCOME_UNKNOWN permanecem Em conciliação e não geram evento terminal até existir confirmação conclusiva da liquidante.
EventoQuando é enviado
payment.createdTransação criada
payment.pendingPagamento aguardando confirmação
payment.action_requiredCartão aguardando confirmação do titular ou desafio 3DS
payment.authorizedCartão autorizado e aguardando conclusão
payment.paidPagamento confirmado
payment.failedPagamento recusado ou expirado
payment.refundedPagamento estornado
withdrawal.createdSaque solicitado
withdrawal.processingSaque enviado para processamento
withdrawal.completedSaque concluído
withdrawal.failedSaque não concluído
withdrawal.cancelledSaque cancelado
advance.completedAntecipação aprovada e creditada
advance.rejectedAntecipação recusada

Exemplo de webhook de saque

O objeto receipt só é preenchido após a conclusão do saque.
{
  "id": "evt_wd_01_withdrawal_completed_1787630400000",
  "type": "withdrawal.completed",
  "createdAt": "2026-08-25T10:00:00.000Z",
  "data": {
    "id": "wd_01",
    "status": "COMPLETED",
    "rail": "PIX",
    "currency": "BRL",
    "amount": 100.00,
    "fee": 1.00,
    "netAmount": 99.00,
    "destination": { "pixKey": "cliente@example.com", "pixType": "EMAIL" },
    "receipt": { "endToEndId": "E0000000020260825..." },
    "createdAt": "2026-08-25T09:58:00.000Z",
    "updatedAt": "2026-08-25T10:00:00.000Z"
  }
}

Falha transacional e ação necessária

Eventos de falha usam o mesmo objeto seguro da API. O evento nunca revela a liquidante, credenciais ou o payload bruto recebido. Em cartões, payment.action_required informa que o titular precisa concluir o 3DS antes do resultado final.
Responda HTTP 2xx rapidamente, deduplique pelo id do evento e processe o conteúdo em fila. Eventos podem ser repetidos ou chegar fora de ordem.
{
  "id": "evt_pay_01_payment_failed_1787630400000",
  "type": "payment.failed",
  "createdAt": "2026-08-25T10:00:00.000Z",
  "requestId": "req_01J...",
  "data": {
    "id": "pay_01J...",
    "reference": "pedido-123",
    "method": "PIX",
    "status": "FAILED",
    "error": {
      "category": "PROVIDER",
      "leonapayCode": "LP503_PIX_TEMPORARILY_UNAVAILABLE",
      "message": "This payment method is temporarily unavailable. Retry safely with the same idempotency key.",
      "retryable": true,
      "retryAfter": 2,
      "requestId": "req_01J...",
      "docsUrl": "https://docs.leonapay.com.br/docs/errors#lp503-pix-temporarily-unavailable"
    }
  }
}

Falha assíncrona de saque

A criação do saque pode retornar HTTP 201 antes do resultado da rede. Em caso de falha conclusiva, consulte GET /api/v2/withdrawals/{withdrawalId} ou processe withdrawal.failed. Os dois canais devolvem o mesmo objeto data.error persistido.
Não crie uma operação duplicada quando o resultado for inconclusivo. Consulte o ID original e preserve a mesma idempotência.
{
  "id": "evt_wd_01_withdrawal_failed",
  "type": "withdrawal.failed",
  "createdAt": "2026-09-30T15:01:00.000Z",
  "data": {
    "id": "wd_01J...",
    "status": "FAILED",
    "rail": "PIX",
    "currency": "BRL",
    "amount": 100.00,
    "fee": 1.00,
    "error": {
      "category": "VALIDATION",
      "leonapayCode": "LP422_PIX_KEY_INVALID",
      "message": "The PIX key is invalid or was not found.",
      "field": "destination.pixKey",
      "retryable": false,
      "requestId": "req_01J...",
      "docsUrl": "https://docs.leonapay.com.br/docs/errors#lp422-pix-key-invalid"
    }
  }
}

Eventos de PIX

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdQR Code criado
PENDINGpayment.pendingAguardando pagamento
PAIDpayment.paidPagamento confirmado
EXPIREDpayment.expiredQR Code expirado
FAILEDpayment.failedFalha no processamento
REFUNDEDpayment.refundedPagamento devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PIX",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PIX",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PIX",
      "status": "PAID",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PIX",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PIX",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PIX",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  }
]

Eventos de BOLETO

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdBoleto emitido
PENDINGpayment.pendingAguardando compensação
PAIDpayment.paidBoleto compensado
EXPIREDpayment.expiredVencimento encerrado
FAILEDpayment.failedFalha na emissão
REFUNDEDpayment.refundedPagamento devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BOLETO",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BOLETO",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BOLETO",
      "status": "PAID",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BOLETO",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BOLETO",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BOLETO",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  }
]

Eventos de SPEI

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdCLABE disponibilizada
PENDINGpayment.pendingAguardando transferência
PAIDpayment.paidSPEI conciliado
EXPIREDpayment.expiredReferência expirada
FAILEDpayment.failedTransferência rejeitada
REFUNDEDpayment.refundedValor devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "SPEI",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "MXN",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "SPEI",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "MXN",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "SPEI",
      "status": "PAID",
      "amount": 125.9,
      "currency": "MXN",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "SPEI",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "MXN",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "SPEI",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "MXN",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "SPEI",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "MXN",
      "reference": "pedido-123"
    }
  }
]

Eventos de MBWAY

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
ACTION_REQUIREDpayment.action_requiredPedido enviado ao aplicativo
PENDINGpayment.pendingAguardando aprovação no app
PAIDpayment.paidPagamento confirmado
FAILEDpayment.failedPedido recusado
EXPIREDpayment.expiredPedido expirado
REFUNDEDpayment.refundedPagamento devolvido
[
  {
    "id": "evt_action_required",
    "event": "payment.action_required",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "MBWAY",
      "status": "ACTION_REQUIRED",
      "amount": 125.9,
      "currency": "EUR",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "MBWAY",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "EUR",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "MBWAY",
      "status": "PAID",
      "amount": 125.9,
      "currency": "EUR",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "MBWAY",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "EUR",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "MBWAY",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "EUR",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "MBWAY",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "EUR",
      "reference": "pedido-123"
    }
  }
]

Eventos de BANK TRANSFER

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdPagamento criado
REDIRECT_PENDINGpayment.pendingAguardando banco
PAIDpayment.paidPagamento confirmado
CANCELLEDpayment.failedFluxo cancelado
EXPIREDpayment.expiredSessão expirada
REFUNDEDpayment.refundedValor devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BANK_TRANSFER",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "ARS",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_redirect_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BANK_TRANSFER",
      "status": "REDIRECT_PENDING",
      "amount": 125.9,
      "currency": "ARS",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BANK_TRANSFER",
      "status": "PAID",
      "amount": 125.9,
      "currency": "ARS",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_cancelled",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BANK_TRANSFER",
      "status": "CANCELLED",
      "amount": 125.9,
      "currency": "ARS",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BANK_TRANSFER",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "ARS",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BANK_TRANSFER",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "ARS",
      "reference": "pedido-123"
    }
  }
]

Eventos de PSE

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdPagamento criado
PENDINGpayment.pendingAguardando transferência
PAIDpayment.paidPagamento conciliado
FAILEDpayment.failedFalha bancária
EXPIREDpayment.expiredReferência expirada
REFUNDEDpayment.refundedValor devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PSE",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PSE",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PSE",
      "status": "PAID",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PSE",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PSE",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "PSE",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  }
]

Eventos de NEQUI

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdPagamento criado
PENDINGpayment.pendingAguardando confirmação
PAIDpayment.paidPagamento confirmado
FAILEDpayment.failedPagamento rejeitado
EXPIREDpayment.expiredPrazo encerrado
REFUNDEDpayment.refundedValor devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "NEQUI",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "NEQUI",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "NEQUI",
      "status": "PAID",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "NEQUI",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "NEQUI",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "NEQUI",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  }
]

Eventos de BREB

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdPagamento criado
PENDINGpayment.pendingAguardando confirmação
PAIDpayment.paidPagamento confirmado
FAILEDpayment.failedPagamento rejeitado
EXPIREDpayment.expiredPrazo encerrado
REFUNDEDpayment.refundedValor devolvido
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BREB",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_pending",
    "event": "payment.pending",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BREB",
      "status": "PENDING",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BREB",
      "status": "PAID",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_failed",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BREB",
      "status": "FAILED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_expired",
    "event": "payment.expired",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BREB",
      "status": "EXPIRED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "BREB",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "COP",
      "reference": "pedido-123"
    }
  }
]

Eventos de CREDIT CARD

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdAutorização iniciada
THREE_DS_REQUIREDpayment.action_requiredAutenticação necessária
AUTHORIZEDpayment.authorizedValor autorizado
PAIDpayment.paidCaptura concluída
DECLINEDpayment.failedEmissor recusou
REFUNDEDpayment.refundedEstorno concluído
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "CREDIT_CARD",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_three_ds_required",
    "event": "payment.action_required",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "CREDIT_CARD",
      "status": "THREE_DS_REQUIRED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_authorized",
    "event": "payment.authorized",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "CREDIT_CARD",
      "status": "AUTHORIZED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "CREDIT_CARD",
      "status": "PAID",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_declined",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "CREDIT_CARD",
      "status": "DECLINED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "CREDIT_CARD",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  }
]

Eventos de DEBIT CARD

A LeonaPay envia um novo evento sempre que o pagamento muda de estado. O campo occurredAt representa o momento efetivo da alteração.
StatusEventoSituação
CREATEDpayment.createdPagamento iniciado
THREE_DS_REQUIREDpayment.action_requiredAutenticação necessária
PAIDpayment.paidDébito confirmado
DECLINEDpayment.failedEmissor recusou
CANCELLEDpayment.failedPagamento cancelado
REFUNDEDpayment.refundedEstorno concluído
[
  {
    "id": "evt_created",
    "event": "payment.created",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "DEBIT_CARD",
      "status": "CREATED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_three_ds_required",
    "event": "payment.action_required",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "DEBIT_CARD",
      "status": "THREE_DS_REQUIRED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_paid",
    "event": "payment.paid",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "DEBIT_CARD",
      "status": "PAID",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_declined",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "DEBIT_CARD",
      "status": "DECLINED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_cancelled",
    "event": "payment.failed",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "DEBIT_CARD",
      "status": "CANCELLED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  },
  {
    "id": "evt_refunded",
    "event": "payment.refunded",
    "occurredAt": "2026-08-20T14:01:12Z",
    "data": {
      "id": "pay_01J5VX8M8W8W6Q",
      "method": "DEBIT_CARD",
      "status": "REFUNDED",
      "amount": 125.9,
      "currency": "BRL",
      "reference": "pedido-123"
    }
  }
]

Validar assinatura

Cada entrega traz x-leonapay-timestamp (segundos Unix), x-leonapay-event-id, x-leonapay-event e x-leonapay-signature no formato sha256=<hex>. A mensagem assinada é {timestamp}.{eventId}.{corpo bruto}, unida por pontos, nessa ordem: o valor de x-leonapay-timestamp, o valor de x-leonapay-event-id e o corpo exatamente como chegou, antes de qualquer parse. A chave do HMAC SHA-256 é o secret devolvido na criação do webhook (whsec_…), usado inteiro, como texto. Compare em tempo constante e recuse entregas com o timestamp a mais de 5 minutos do seu relógio.
import { createHmac, timingSafeEqual } from "node:crypto";

const timestamp = request.headers["x-leonapay-timestamp"];
const eventId = request.headers["x-leonapay-event-id"];
const received = request.headers["x-leonapay-signature"]; // "sha256=<hex>"

const digest = createHmac("sha256", webhookSecret) // "whsec_..."
  .update(`${timestamp}.${eventId}.${rawRequestBody}`, "utf8")
  .digest("hex");
const expected = `sha256=${digest}`;

const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const valid = fresh && expected.length === received.length &&
  timingSafeEqual(Buffer.from(expected), Buffer.from(received));
LeonaPay Developers · API v2