Eventos
Cada evento chega com o mesmo corpo: id (evt_…), type, createdAt, environment e data, o recurso como estava no momento do evento, no mesmo formato da API.
Tipos
| Evento | Quando | data |
|---|---|---|
charge.created | Cobrança criada; o checkout já pode ser enviado. | charge |
charge.paid | O pagador pagou. Tarifa e líquido já estão no extrato. | charge |
charge.underpaidem breve | Cripto: chegou menos que o valor. | charge |
charge.overpaidem breve | Cripto: chegou mais que o valor. | charge |
charge.late_paymentem breve | Cripto: pagamento depois do prazo. | charge |
charge.expired | O prazo acabou sem pagamento. | charge |
charge.canceled | A cobrança foi cancelada antes do pagamento. | charge |
charge.failed | A cobrança terminou sem pagamento por falha do provider ou do banco. | charge |
charge.refunded | Devolvida por inteiro para quem pagou (devolução ou MED perdido). | charge |
charge.partially_refunded | Parte do valor voltou para quem pagou (devolução ou MED perdido). | charge |
payout.created | Pagamento por PIX pedido (pode aguardar aprovação). | payout |
payout.approved | A aprovação liberou o pagamento; o status diz se segue para a análise da plataforma ou para o envio. | payout |
payout.paid | O pagamento saiu e chegou ao destino. | payout |
payout.failed | O pagamento não foi concluído: falhou, foi recusado ou cancelado (veja o status). O valor volta ao saldo. | payout |
payout.returned | O destino devolveu o valor; ele volta ao saldo. | payout |
refund.created | Devolução pedida. | refund |
refund.succeeded | A devolução chegou a quem pagou. | refund |
refund.failed | A devolução não foi concluída; o valor volta ao saldo. | refund |
dispute.created | Abriu uma MED; a defesa pode ser montada no painel ou pela API. | dispute |
dispute.updated | A MED mudou de etapa. | dispute |
dispute.closed | A MED foi encerrada, com o resultado. | dispute |
payment_link.created | Link de pagamento criado. | |
payment_link.updated | O link mudou: nome, limite, validade ou status (pausado, reativado, arquivado). | |
test.ping | Evento de teste enviado pelo painel para conferir o endpoint. | { message } |
No painel, cada endpoint escolhe os grupos que recebe: charge.*, payout.*, refund.*, dispute.* e payment_link.*. O test.ping não pertence a grupo: só sai pelo botão "Enviar teste", para aquele endpoint.
O que vem em data
charge.*: o recursochargesemcheckoutUrl,customereattempt, que só a API devolve.payout.*,refund.*edispute.*: o recurso inteiro, igual ao da API (na disputa, sem as evidências e a defesa, que vêm só noGET /v1/disputes/:id).environmentdiz de qual ambiente veio. Os endpoints de teste só recebem eventos de teste, e os de produção, só de produção.
O que não gera evento
- A primeira de duas aprovações da plataforma (quatro olhos): o payout.approved sai quando o pagamento é liberado.
- Link esgotado ou expirado: o estado é calculado na leitura (state no recurso), não muda nada guardado.
- Cadastro de chaves e de endpoints, que acontece no painel.
Perdeu algum? GET /v1/events (escopo webhooks: read) lista os eventos do ambiente da chave, do mais recente para o mais antigo, com cursor e filtro ?type=; GET /v1/events/:id devolve um pelo X-Event-Id. O test.ping não aparece.
A entrega é "pelo menos uma vez" e a ordem de chegada não é garantida: um evento que falhou chega depois de outros mais novos. Decida pelo status em data e pelo createdAt, ou consulte o recurso pela API. Mais em Tentativas e cabeçalhos.