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.| Evento | Quando é enviado |
|---|---|
payment.created | Transação criada |
payment.pending | Pagamento aguardando confirmação |
payment.action_required | Cartão aguardando confirmação do titular ou desafio 3DS |
payment.authorized | Cartão autorizado e aguardando conclusão |
payment.paid | Pagamento confirmado |
payment.failed | Pagamento recusado ou expirado |
payment.refunded | Pagamento estornado |
withdrawal.created | Saque solicitado |
withdrawal.processing | Saque enviado para processamento |
withdrawal.completed | Saque concluído |
withdrawal.failed | Saque não concluído |
withdrawal.cancelled | Saque cancelado |
advance.completed | Antecipação aprovada e creditada |
advance.rejected | Antecipaçã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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | QR Code criado |
PENDING | payment.pending | Aguardando pagamento |
PAID | payment.paid | Pagamento confirmado |
EXPIRED | payment.expired | QR Code expirado |
FAILED | payment.failed | Falha no processamento |
REFUNDED | payment.refunded | Pagamento 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Boleto emitido |
PENDING | payment.pending | Aguardando compensação |
PAID | payment.paid | Boleto compensado |
EXPIRED | payment.expired | Vencimento encerrado |
FAILED | payment.failed | Falha na emissão |
REFUNDED | payment.refunded | Pagamento 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | CLABE disponibilizada |
PENDING | payment.pending | Aguardando transferência |
PAID | payment.paid | SPEI conciliado |
EXPIRED | payment.expired | Referência expirada |
FAILED | payment.failed | Transferência rejeitada |
REFUNDED | payment.refunded | Valor 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.| Status | Evento | Situação |
|---|---|---|
ACTION_REQUIRED | payment.action_required | Pedido enviado ao aplicativo |
PENDING | payment.pending | Aguardando aprovação no app |
PAID | payment.paid | Pagamento confirmado |
FAILED | payment.failed | Pedido recusado |
EXPIRED | payment.expired | Pedido expirado |
REFUNDED | payment.refunded | Pagamento 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Pagamento criado |
REDIRECT_PENDING | payment.pending | Aguardando banco |
PAID | payment.paid | Pagamento confirmado |
CANCELLED | payment.failed | Fluxo cancelado |
EXPIRED | payment.expired | Sessão expirada |
REFUNDED | payment.refunded | Valor 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Pagamento criado |
PENDING | payment.pending | Aguardando transferência |
PAID | payment.paid | Pagamento conciliado |
FAILED | payment.failed | Falha bancária |
EXPIRED | payment.expired | Referência expirada |
REFUNDED | payment.refunded | Valor 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Pagamento criado |
PENDING | payment.pending | Aguardando confirmação |
PAID | payment.paid | Pagamento confirmado |
FAILED | payment.failed | Pagamento rejeitado |
EXPIRED | payment.expired | Prazo encerrado |
REFUNDED | payment.refunded | Valor 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Pagamento criado |
PENDING | payment.pending | Aguardando confirmação |
PAID | payment.paid | Pagamento confirmado |
FAILED | payment.failed | Pagamento rejeitado |
EXPIRED | payment.expired | Prazo encerrado |
REFUNDED | payment.refunded | Valor 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Autorização iniciada |
THREE_DS_REQUIRED | payment.action_required | Autenticação necessária |
AUTHORIZED | payment.authorized | Valor autorizado |
PAID | payment.paid | Captura concluída |
DECLINED | payment.failed | Emissor recusou |
REFUNDED | payment.refunded | Estorno 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.| Status | Evento | Situação |
|---|---|---|
CREATED | payment.created | Pagamento iniciado |
THREE_DS_REQUIRED | payment.action_required | Autenticação necessária |
PAID | payment.paid | Débito confirmado |
DECLINED | payment.failed | Emissor recusou |
CANCELLED | payment.failed | Pagamento cancelado |
REFUNDED | payment.refunded | Estorno 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));