event que a Chargefy registra hoje. Cada event
fica disponível na API de Eventos e também pode
ser entregue aos endpoints de webhook inscritos naquele tipo.
Clique em um tipo para ver o payload completo, os campos esperados e um exemplo
do event.
Os tipos de evento usam namespaces separados por ponto, sem _. O payload do
recurso fica sempre em data.object.
data.object contém o objeto público completo no estado do evento. Quando
data.previous_attributes existir, somente ele é parcial e contém os valores
anteriores dos campos alterados.Ao configurar um endpoint de webhook, inscreva os valores exatamente como
aparecem nesta página. Wildcards como
payment.intent.*, charge.* ou *
não são aceitos em webhook_endpoint.events.Em eventos entregues a uma plataforma, o campo top-level
organization
identifica a conta conectada que originou o evento. Para reler essa conta, use
GET /v1/organizations/{organization} sem o header Organization. Todos os
eventos organization.* são exclusivos de endpoints com
events_from: "platform".Encontre por recurso
| Se você procura | Vá direto para |
|---|---|
| Ciclo do pagamento | payment.intent.created, payment.intent.updated, payment.intent.succeeded e payment.intent.canceled |
| Tentativa concreta de cobrança | Eventos charge.* |
| Método salvo sem cobrança | Eventos setup.intent.* e payment.method.* |
| Extrato, recebíveis, taxas e liquidação | Eventos transaction.*, que representam os movimentos do extrato |
| Criação, ativação e revisão de conta conectada | Eventos organization.* |
| Como cadastrar os tipos | Criar Webhook Endpoint |
| Assinatura, retry, ordem e duplicação | Entrega de webhooks |
Eventos
| Evento | Payload | Quando acontece |
|---|---|---|
payout.account.created | payout_account | Ocorre quando uma conta para saques é criada e conectada à organização atuante. |
payout.account.detached | payout_account | Ocorre quando uma conta para saques é desconectada da organização atuante, sem remover o destino preservado no cadastro financeiro. |
charge.dispute.closed | dispute | Ocorre quando uma disputa é encerrada em won, lost ou warning_closed — incluindo o encerramento automático como lost quando o prazo termina sem nenhum campo de arquivo preenchido ou quando a análise passa de 130 dias desde o envio da defesa sem decisão favorável. |
charge.dispute.created | dispute | Ocorre quando uma disputa é aberta para uma cobrança. |
charge.dispute.funds.reinstated | dispute | Ocorre quando o dinheiro de uma disputa ganha volta ao extrato, num movimento positivo em transactions. |
charge.dispute.funds.withdrawn | dispute | Ocorre quando a disputa tira o dinheiro da venda do extrato, num movimento negativo em transactions. |
charge.dispute.updated | dispute | Ocorre quando uma disputa muda de estado, tem campos de evidência preenchidos ou limpos, ou tem a defesa enviada — por você ou automaticamente no fim do prazo. |
charge.failed | charge | Ocorre quando uma tentativa de cobrança chega ao estado failed. |
charge.refunded | charge | Ocorre quando uma tentativa de cobrança recebe um refund parcial ou total. |
charge.succeeded | charge | Ocorre quando uma tentativa de cobrança chega ao estado succeeded. |
charge.updated | charge | Ocorre quando uma cobrança muda sem entrar diretamente nos estados finais succeeded ou failed. |
checkout.session.async.payment.failed | checkout.session | Ocorre quando um pagamento assíncrono de checkout, como Pix ou boleto, falha ou expira depois do checkout ter sido concluído. |
checkout.session.async.payment.succeeded | checkout.session | Ocorre quando um pagamento assíncrono de checkout, como Pix ou boleto, é confirmado depois do checkout ter sido concluído. |
checkout.session.completed | checkout.session | Ocorre quando o comprador confirma a checkout session; em cartão, o pagamento pode já estar aprovado, e em Pix ou boleto ainda pode ficar pendente. |
checkout.session.created | checkout.session | Ocorre quando uma checkout session é criada pela API, pelo dashboard ou a partir de um payment link. |
checkout.session.expired | checkout.session | Ocorre quando uma checkout session ainda aberta expira antes do comprador concluir o checkout. |
customer.created | customer | Ocorre quando um customer é criado pela API ou materializado automaticamente durante um checkout ou cobrança. |
customer.deleted | customer | Ocorre quando um customer é removido e deixa de aparecer nas consultas da API. |
customer.updated | customer | Ocorre quando dados públicos de um customer mudam, como email, documento, telefone, endereço de cobrança ou metadata. |
invoice.created | invoice | Ocorre quando uma invoice é criada e fica pronta para cobrança. |
invoice.paid | invoice | Ocorre quando uma invoice chega ao estado paid, incluindo cobranças de assinatura, invoices manuais pagas, trials e assinaturas com valor zero. |
invoice.payment.failed | invoice | Ocorre quando uma tentativa de pagamento de invoice falha e a invoice pode permanecer aberta para nova tentativa. |
invoice.voided | invoice | Ocorre quando uma invoice é marcada como void. |
organization.created | organization | Ocorre quando uma organização conectada é criada e vinculada a uma plataforma. |
organization.deleted | organization | Ocorre quando uma organização conectada é excluída; data.object traz o último estado anterior ao fechamento. |
organization.review.required | organization_review | Ocorre quando uma organização conectada precisa confirmar ou atualizar dados cadastrais. |
organization.review.submitted | organization_review | Ocorre quando a organização conectada envia o formulário hospedado de atualização cadastral. |
organization.updated | organization | Ocorre quando o status de ativação financeira, a lista de tarefas da ativação (requirements) ou dados públicos de uma organização conectada mudam. |
payment.intent.canceled | payment_intent | Ocorre quando um payment intent é cancelado de forma deliberada: cancelamento direto, expiração da sessão de checkout ou fatura anulada. |
payment.intent.created | payment_intent | Ocorre quando um payment intent é criado. |
payment.intent.succeeded | payment_intent | Ocorre quando um payment intent chega ao estado succeeded e o pagamento foi confirmado. |
payment.intent.updated | payment_intent | Ocorre quando campos ou estados intermediários mudam: a confirmação coloca um Pix em requires_action, uma recusa ou um código vencido devolve o intent a requires_payment_method, ou um regenerate emite código novo. |
payment.link.created | payment_link | Ocorre quando um payment link é criado. |
payment.link.updated | payment_link | Ocorre quando um payment link é atualizado ou desativado. |
payment.method.attached | payment_method | Ocorre quando um payment method vira o método padrão de um customer. |
payment.method.created | payment_method | Ocorre quando a confirmação de um setup intent materializa um payment method salvo. |
payment.method.detached | payment_method | Ocorre quando um payment method deixa de ser o método padrão do customer, sem apagar a credencial salva. |
payment.method.updated | payment_method | Ocorre quando dados públicos de um payment method são atualizados. |
price.created | price | Ocorre quando um price é criado diretamente ou inline durante a criação de um product. |
price.updated | price | Ocorre quando um price é atualizado ou desativado. |
product.created | product | Ocorre quando um product é criado. |
product.updated | product | Ocorre quando um product é atualizado ou desativado. |
refund.created | refund | Ocorre quando um refund é criado. |
refund.failed | refund | Ocorre quando um refund chega ao estado failed. |
refund.updated | refund | Ocorre quando um refund muda de estado. |
transaction.created | transaction | Ocorre quando um movimento entra no extrato da organização. |
transaction.paid | transaction | Ocorre quando um movimento do extrato é liquidado. |
transaction.canceled | transaction | Ocorre quando um movimento é cancelado antes de liquidar. |
transaction.refunded | transaction | Ocorre quando um movimento é revertido por estorno da venda. |
setup.intent.canceled | setup_intent | Ocorre quando um setup intent chega ao estado canceled. |
setup.intent.created | setup_intent | Ocorre quando um setup intent é criado para salvar um método de pagamento. |
setup.intent.failed | setup_intent | Ocorre quando a confirmação de um setup intent falha. |
setup.intent.succeeded | setup_intent | Ocorre quando um setup intent é confirmado e o método de pagamento fica salvo para o customer. |
subscription.canceled | subscription | Ocorre quando uma subscription passa para canceled, imediatamente ou ao fim de um cancelamento agendado. |
subscription.created | subscription | Ocorre quando uma subscription é criada. |
subscription.paused | subscription | Ocorre quando uma subscription passa para paused. |
subscription.pending.update.applied | subscription | Ocorre quando uma pending update é aplicada à subscription. |
subscription.pending.update.expired | subscription | Ocorre quando uma pending update expira antes de ser aplicada. |
subscription.resumed | subscription | Ocorre quando uma subscription pausada volta para cobrança normal. |
subscription.trial.will.end | subscription | Ocorre antes do fim de um trial enquanto a subscription ainda está trialing. |
subscription.updated | subscription | Ocorre quando uma subscription muda, incluindo status, método de pagamento, datas de ciclo ou metadata. |
Eventos aposentados
Tipos que a Chargefy já entregou e não emite mais. Se algum deles ainda estiver na inscrição do seu endpoint, troque pelo substituto: o tipo antigo não é mais recusado nem entregue, ele simplesmente nunca chega.| Tipo aposentado | Use no lugar | Por quê |
|---|---|---|
payment.intent.failed | charge.failed + payment.intent.updated | Uma recusa encerra a tentativa, não a cobrança. Quem falhou foi a charge; o payment intent volta para requires_payment_method e aceita uma nova tentativa no mesmo objeto. |
Cobrança de fatura continua sinalizando pela régua:
invoice.payment.failed é
emitido quando a tentativa de uma fatura falha, e não foi afetado.
