charge.updated, entregue só ao postbackUrl, complementa esses eventos com recusas assíncronas e com o chargeback formalizado.
Para o negócio:
charge.paid é o sinal para liberar o pedido, charge.refunded é o sinal para registrar a devolução e charge.blocked avisa que uma venda entrou em análise de disputa. O chargeback formalizado chega pelo charge.updated, no postbackUrl, e, quando o valor é revertido do saldo, também como charge.refunded. Se a sua operação vende com Pix, o charge.paid é a forma automática de saber que o cliente pagou.Quando usar
Como funciona
O desenho abaixo mostra quais eventos saem da criação da cobrança até o pagamento ou a recusa. Os eventos do envelope padrão vão aos endpoints e àpostbackUrl. O charge.updated vai só à postbackUrl e também sai em outras situações, como o pagamento de um Pix.
1
A cobrança é criada
Sua aplicação chama
POST /v1/charges. A resposta síncrona traz o id, o status e, no Pix, o QR Code.2
Eventos da criação
A Finvia envia
charge.created. Se o processamento termina em pending (por exemplo, Pix gerado), envia também charge.pending. Se a cobrança é recusada ou falha na criação, envia charge.refused ou charge.failed.3
Pagamento confirmado
Quando o pagamento é confirmado, na hora ou depois, chega
charge.paid com paid_at preenchido.4
Pós-venda
Estorno concluído gera
charge.refunded. Alerta de pré-chargeback gera charge.pre_chargeback. Bloqueio da cobrança gera charge.blocked. Quem informou postbackUrl recebe ainda o charge.updated legado nas situações descritas em Postback legado.Eventos disponíveis
Os endpoints que recebem cada evento seguem a regra da conta dona da cobrança, explicada em Quem recebe cada evento. Uma cobrança que fica em
in_analysis ou authentication_required na criação gera só o charge.created. O evento seguinte depende do desfecho.
Status da cobrança
O campostatus dentro de data pode ter estes valores:
A tabela completa, com o que fazer em cada status, está em Status de cobrança.
Regras de negócio
Envelope padrão
Todos os eventos de cobrança, exceto ocharge.updated, usam o envelope padrão:
id da raiz identifica o evento: cada evento tem o seu, e é ele que a receita de deduplicação usa. livemode é false em cobranças de teste. O objeto data traz a cobrança (o exemplo acima foi resumido).
Campos do objeto data
Objeto customer
Objeto payment_method
As chaves internas ficam em camelCase, no formato em que foram gravadas:
- Cartão de crédito
- Pix
Objeto payment_details (Pix)
A chave externa é payment_details (snake_case), mas os campos internos são camelCase, no mesmo formato da resposta da API:
qrCodeBase64 pode vir null ou ausente em cobranças criadas antes da introdução do campo ou quando a imagem não pôde ser gerada. Nesses casos, gere o QR Code a partir do copyPaste.Objeto shipping_address
As chaves internas ficam em camelCase, como foram enviadas em shippingAddress na criação da cobrança. O país volta exatamente como foi enviado, no padrão ISO 3166-1 alpha-3 (envie em maiúsculas, como BRA).
Objeto tracking_info
trackingStatus pode ser awaiting_shipment, on_the_way ou delivered.
Payloads por evento
- charge.created
- charge.pending
- charge.paid
- charge.refused
- charge.refunded
- charge.blocked
Enviado logo após a criação de uma nova cobrança.
Repare nos exemplos que
spread e net podem mudar entre charge.pending e charge.paid (de 0 e 96.5 para 1 e 95.5). Grave os valores financeiros a partir do charge.paid ou da consulta à API depois do pagamento.Recusas
Conforme o adquirente, o status final de uma recusa assíncrona pode ser
failed em vez de refused. No adquirente principal de cartão, a recusa assíncrona, o cancelamento e a expiração terminam em failed. Trate os dois valores como “não pago”.
Bloqueio
Quando a cobrança é bloqueada, por exemplo por um MED (Mecanismo Especial de Devolução, do Pix) ou por um chargeback em análise, a Finvia enviacharge.blocked aos endpoints e ao postbackUrl. Quem tem postbackUrl recebe também o charge.updated.
- O status continua
paid. O bloqueio é uma marcação:is_blocked: true, comblocked_ateblocked_reason(nocharge.updated,isBlocked,blockedAteblockedReason). blocked_reasoné um texto livre preenchido pela Finvia e pode vir vazio. Não decida o fluxo por ele.- A liberação do bloqueio não gera evento. Para saber se uma cobrança continua bloqueada, consulte
GET /v1/charges/{id}e leiaisBlocked. OblockedAtcontinua preenchido depois da liberação, então não o use para esse fim. GET /v1/charges?status=blockedlista as cobranças bloqueadas.
Pré-chargeback
Um alerta de pré-chargeback chega quando o portador contestou a compra junto ao banco emissor antes de o chargeback ser formalizado (programas como Ethoca e Verifi). A cobrança passa para o statuspre_chargeback, e a Finvia envia:
charge.pre_chargeback, no envelope padrão, aos endpoints e aopostbackUrl;charge.updatedaopostbackUrl, comchargebackAlertRefundedechargebackAlertReason;charge.refunded, comchargeback_alert_refunded: true, quando o valor é estornado como parte do tratamento do alerta.
Ao registrar o alerta, a Finvia decide se devolve ou não o valor (por padrão, devolve):
- Com estorno (o caso padrão): o valor é devolvido imediatamente ao portador para evitar que o alerta vire um chargeback formal, com as taxas e penalidades que ele traz. O pedido deve ser tratado como estornado.
- Sem estorno: decisão operacional de contestar e não devolver (por exemplo, mercadoria já entregue com prova de entrega). A disputa segue aberta e o pedido não deve ser marcado como estornado.
Para o negócio: num pré-chargeback com estorno, o dinheiro já saiu. Se o produto ainda não foi enviado, segure o envio. Se já foi, acione o seu processo de recuperação com o cliente. No caso sem estorno, prepare a documentação de entrega, porque a disputa continua.
Chargeback formalizado
Não existe um evento dedicado ao chargeback formalizado no envelope padrão. Quando o adquirente informa a disputa, a cobrança passa parachargeback e a Finvia avisa assim:
A transição automática para
chargeback acontece nos adquirentes de cartão que enviam esse aviso. Em qualquer caso, confirme o estado com GET /v1/charges/{id} antes de registrar a perda.
O desenho abaixo resume os eventos que podem chegar depois que a cobrança foi paga.
Onde aparece + charge.updated, esse evento chega só à postbackUrl.
Postback legado
Ocharge.updated é entregue exclusivamente ao postbackUrl informado na criação da cobrança, nunca aos endpoints, e tem envelope e convenção de nomes próprios. Ele é enviado quando:
- o adquirente informa uma mudança de status pelo webhook dele: pagamento, recusa ou falha assíncrona, estorno, chargeback;
- o 3DS gerenciado termina em recusa ou falha;
- a cobrança é bloqueada;
- a cobrança recebe um alerta de pré-chargeback.
charge.paid e também charge.updated no postbackUrl.
Envelope do charge.updated (camelCase)
O envelope não temid nem livemode. O objeto data é a cobrança convertida para camelCase em todos os níveis, inclusive as chaves de metadata:
O
charge.updated traz mais campos que o envelope padrão. Use só os documentados nesta página. Em cobranças Pix, paymentDetails traz os mesmos campos descritos em Objeto payment_details (Pix).
Passo a passo
O exemplo trata os dois formatos (envelope padrão echarge.updated) na mesma rota. Ele responde primeiro e processa depois. Para descartar eventos repetidos, aplique antes do switch a receita de deduplicação, como no exemplo completo da visão geral.
Node.js
Fluxo típico de um Pix
O desenho abaixo mostra o fluxo típico de um Pix, com os webhooks de cada etapa.1
Sua aplicação cria a cobrança
POST /v1/charges com paymentMethod.type pix.2
A resposta traz o QR Code
A resposta síncrona traz o
id, status pending e o QR Code. Mostre-o ao cliente.3
Webhooks de criação e espera
Chegam
charge.created e charge.pending.4
O cliente paga
O cliente paga o Pix no aplicativo do banco.
5
Webhook de pagamento
Chega
charge.paid e, se a cobrança tem postbackUrl, também o charge.updated. Sua aplicação confirma em GET /v1/charges/{id} e libera o acesso.Erros comuns
Perguntas frequentes
Qual evento devo usar para liberar o pedido?
Qual evento devo usar para liberar o pedido?
charge.paid, sempre confirmado por GET /v1/charges/{id}. Os webhooks não têm assinatura HMAC, por isso a confirmação na API é necessária antes de liberar.Por que existem dois formatos de payload?
Por que existem dois formatos de payload?
O envelope padrão atende os eventos entregues aos endpoints e ao
postbackUrl. O charge.updated é um canal legado, entregue só ao postbackUrl, com a cobrança em camelCase. Os dois formatos são mantidos por compatibilidade com integrações em produção.Recebo webhook de recusa de cartão?
Recebo webhook de recusa de cartão?
Sim, quando a recusa acontece na criação ou ao final do 3DS gerenciado: chega
charge.refused ou charge.failed. A resposta de POST /v1/charges continua sendo a fonte principal, com o motivo em reason. Recusas informadas depois pelo adquirente chegam só pelo charge.updated.Como recebo aviso de chargeback e MED?
Como recebo aviso de chargeback e MED?
O bloqueio chega como
charge.blocked, nos endpoints e no postbackUrl. O chargeback formalizado chega como charge.updated com status: "chargeback" no postbackUrl e, quando o valor sai do saldo, também como charge.refunded. A liberação do bloqueio não gera aviso. O fluxo completo está em Bloqueio, chargeback e MED.Sou conta master. Recebo os eventos das cobranças das subcontas?
Sou conta master. Recebo os eventos das cobranças das subcontas?
Sim, se o seu endpoint tiver a opção de incluir subcontas (
include_submerchants: true). O merchant_id do payload indica a subconta. Veja Quem recebe cada evento.Como testar
Para testar o tratamento de outros status, use
POST /v1/charges/{id}/resend-webhook com uma cobrança de teste. A rota aceita paid, pending, refused, failed, refunded, in_analysis e authentication_required, gera um evento novo e não muda a cobrança. Bloqueio, pré-chargeback e chargeback não podem ser simulados por ela.
Veja também
Webhooks: visão geral
Destinos, formatos, entrega e deduplicação.
Bloqueio, chargeback e MED
O fluxo de disputa e o campo isBlocked.
Status de cobrança
Todos os status e o que fazer em cada um.
Reenviar webhook de teste
Simule eventos no sandbox.

