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

Tipos de evento
EventoQuandodata
charge.createdCobrança criada; o checkout já pode ser enviado.charge
charge.paidO pagador pagou. Tarifa e líquido já estão no extrato.charge
charge.underpaidem breveCripto: chegou menos que o valor.charge
charge.overpaidem breveCripto: chegou mais que o valor.charge
charge.late_paymentem breveCripto: pagamento depois do prazo.charge
charge.expiredO prazo acabou sem pagamento.charge
charge.canceledA cobrança foi cancelada antes do pagamento.charge
charge.failedA cobrança terminou sem pagamento por falha do provider ou do banco.charge
charge.refundedDevolvida por inteiro para quem pagou (devolução ou MED perdido).charge
charge.partially_refundedParte do valor voltou para quem pagou (devolução ou MED perdido).charge
payout.createdPagamento por PIX pedido (pode aguardar aprovação).payout
payout.approvedA aprovação liberou o pagamento; o status diz se segue para a análise da plataforma ou para o envio.payout
payout.paidO pagamento saiu e chegou ao destino.payout
payout.failedO pagamento não foi concluído: falhou, foi recusado ou cancelado (veja o status). O valor volta ao saldo.payout
payout.returnedO destino devolveu o valor; ele volta ao saldo.payout
refund.createdDevolução pedida.refund
refund.succeededA devolução chegou a quem pagou.refund
refund.failedA devolução não foi concluída; o valor volta ao saldo.refund
dispute.createdAbriu uma MED; a defesa pode ser montada no painel ou pela API.dispute
dispute.updatedA MED mudou de etapa.dispute
dispute.closedA MED foi encerrada, com o resultado.dispute
payment_link.createdLink de pagamento criado.
payment_link.updatedO link mudou: nome, limite, validade ou status (pausado, reativado, arquivado).
test.pingEvento 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 recurso charge sem checkoutUrl, customer e attempt, que só a API devolve.
  • payout.*, refund.* e dispute.*: o recurso inteiro, igual ao da API (na disputa, sem as evidências e a defesa, que vêm só no GET /v1/disputes/:id).
  • environment diz 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.