Skip to main content
Os webhooks de cobrança avisam o seu sistema a cada passo de uma cobrança (charge): quando ela é criada, quando aguarda pagamento, quando é paga, recusada ou estornada, e quando entra em disputa. O postback legado 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 campo status 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

O status chargeback e as recusas assíncronas só chegam pelo charge.updated. Os endpoints recebem, no chargeback, apenas o charge.refunded, e só quando o valor é revertido do saldo. Se a sua operação precisa desses avisos, informe postbackUrl em todas as cobranças. Sem ele, confirme o estado das cobranças em disputa ou em análise com GET /v1/charges/{id}.

Envelope padrão

Todos os eventos de cobrança, exceto o charge.updated, usam o envelope padrão:
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

Para o desenvolvedor: use paid_at como data oficial do pagamento na sua conciliação. O webhook pode chegar bem depois do pagamento.

Objeto customer

Objeto payment_method

As chaves internas ficam em camelCase, no formato em que foram gravadas:

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

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 envia charge.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, com blocked_at e blocked_reason (no charge.updated, isBlocked, blockedAt e blockedReason).
  • 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 leia isBlocked. O blockedAt continua preenchido depois da liberação, então não o use para esse fim.
  • GET /v1/charges?status=blocked lista as cobranças bloqueadas.
O fluxo completo, com os desfechos, está em Bloqueio, chargeback e MED.

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 status pre_chargeback, e a Finvia envia:
  • charge.pre_chargeback, no envelope padrão, aos endpoints e ao postbackUrl;
  • charge.updated ao postbackUrl, com chargebackAlertRefunded e chargebackAlertReason;
  • charge.refunded, com chargeback_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 para chargeback 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

O charge.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.
Por isso, um Pix pago gera charge.paid e também charge.updated no postbackUrl.

Envelope do charge.updated (camelCase)

O envelope não tem id 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).
Para o desenvolvedor: o charge.updated não tem id de evento. Use a chave definida na receita de deduplicação.

Passo a passo

O exemplo trata os dois formatos (envelope padrão e charge.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
Para o desenvolvedor: cobranças de assinatura pagas também disparam charge.created e charge.paid. O metadata dessas cobranças traz subscription_id e billing_cycle, o que permite saber que o pagamento é de uma assinatura. Veja Webhooks de assinatura.

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

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.
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.
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.
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.
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.