Skip to main content
Depois de paga, uma cobrança ainda pode ser contestada. No cartão, o titular pede ao banco emissor que desfaça a compra (chargeback). No Pix, a instituição do pagador pode pedir a devolução pelo MED (Mecanismo Especial de Devolução). Enquanto o caso é analisado, a equipe Finvia pode bloquear a cobrança e reter o valor. Esta página explica cada etapa, os avisos que você recebe, como enviar a defesa e como tratar cada desfecho.
Para o negócio: o aviso de chargeback ou MED chega por e-mail, com os detalhes do caso. A defesa é enviada respondendo a esse e-mail, dentro do prazo indicado nele. Pela API, o seu sistema acompanha o bloqueio e o desfecho, mas não envia defesa. Se a disputa for ganha, o bloqueio é retirado e o valor fica com você. Se for perdida, o valor volta ao comprador.

Conceitos

Em validação (V-32 e V-53): compliance revisa a definição do MED, a citação normativa e o texto do fluxo de defesa (MED e chargeback), inclusive o prazo para envio de evidências.

Quando usar este guia

Como você fica sabendo

O aviso operacional e o aviso técnico chegam por canais diferentes. Na API não existe status nem evento chamado MED. O MED aparece como bloqueio da cobrança.
O status chargeback só é avisado pelo charge.updated, que vai somente à postbackUrl. Os endpoints recebem apenas o charge.refunded, e só quando o valor é revertido do saldo. Informe a postbackUrl em todas as cobranças de cartão e confirme sempre com GET /v1/charges/{id}.

Como funciona o bloqueio

O desenho abaixo mostra como uma contestação chega ao bloqueio da cobrança e quais avisos saem em cada canal. A liberação do bloqueio não gera webhook. Veja Desfechos.
1

Cobrança paga

A cobrança está paid. Só cobranças paid podem ser bloqueadas.
2

A Finvia é notificada

No Pix, a instituição do pagador abre o MED. No cartão, o emissor abre a disputa e ela chega pela adquirente. Você recebe o alerta por e-mail.
3

A equipe Finvia bloqueia a cobrança

O bloqueio é aplicado pela equipe Finvia (ele não chega automaticamente do banco). A cobrança continua paid e passa a ter isBlocked: true, blockedAt e blockedReason. Os endpoints e a postbackUrl recebem charge.blocked.
4

O valor fica retido

O que a venda já liquidou (o líquido mais as taxas da venda) sai do saldo disponível e vai para o saldo bloqueado. Parcelas que liquidarem enquanto o bloqueio durar também caem no saldo bloqueado.
5

Você envia a defesa

Responda ao e-mail do alerta com as evidências, dentro do prazo indicado.
6

Desfecho

Se a disputa for ganha, o bloqueio é retirado. Se for perdida, o valor volta ao comprador. Veja Desfechos.

O que a API mostra durante o bloqueio

Para listar as cobranças bloqueadas, use GET /v1/charges?status=blocked.

Defesa

Não existe rota de API para enviar defesa de MED ou de chargeback. A defesa é tratada com a equipe Finvia, pelo e-mail do alerta.
1

Leia o e-mail do alerta

Ele traz os detalhes do caso e o prazo para a defesa. No Connect, o e-mail vai para a conta master.
2

Reúna as evidências

Comprovante de entrega, nota fiscal, registro de acesso ao produto digital, conversa com o cliente e qualquer outro documento que mostre que a venda foi legítima e entregue.
3

Responda ao e-mail dentro do prazo

Envie as evidências em resposta ao e-mail do alerta. Uma contestação respondida fora do prazo pode ser perdida mesmo com todas as evidências.
Como cada caso é analisado:
  • Pix (MED): a contestação é aberta pela instituição financeira do pagador e analisada pela instituição do recebedor, seguindo as regras do Pix definidas pelo Banco Central. A Finvia encaminha as suas evidências à instituição responsável pela análise. Se a devolução for aceita, o valor volta ao pagador e a cobrança fica refunded. Se for recusada, o bloqueio é retirado.
  • Cartão (chargeback): a disputa é aberta pelo banco emissor do cartão, por meio da bandeira, e chega à Finvia pela adquirente. A Finvia reúne as suas evidências e as apresenta à adquirente, que as leva ao emissor. O resultado depende do emissor e segue o fluxo das bandeiras.
O desenho abaixo junta a defesa por e-mail e os desfechos possíveis no Pix e no cartão. O fluxo da defesa e o prazo para envio das evidências estão em validação (V-32 e V-53), como indicado no início da página.

Desfechos

A passagem para chargeback acontece quando a adquirente informa a disputa à Finvia. Nem todas as adquirentes enviam esse aviso: confirme sempre o estado com GET /v1/charges/{id}.
Para o desenvolvedor: como a liberação não gera webhook, guarde as cobranças que você marcou como “em disputa” e consulte cada uma periodicamente com GET /v1/charges/{id}, ou compare com a lista de GET /v1/charges?status=blocked. Quando isBlocked voltar a false com status paid, restaure o pedido.

Pré-chargeback

O pré-chargeback é um alerta recebido pelos programas Ethoca e Verifi quando o titular contestou a compra no emissor, antes de o chargeback ser formalizado. O serviço é ativado conforme o seu contrato:
  • Alerta com reembolso automático, quando previsto em contrato: o valor é devolvido ao titular para que o alerta não evolua para chargeback formal.
  • O custo do serviço de pré-alerta (Ethoca/Verifi) é debitado da sua conta.
Na API, a cobrança passa para pre_chargeback e os endpoints e a postbackUrl recebem charge.pre_chargeback. A postbackUrl recebe também o charge.updated. Se houve reembolso, sai ainda charge.refunded, com chargeback_alert_refunded: true no payload. Uma cobrança já estornada no pré-chargeback não pode receber outro estorno. Se depois o chargeback for formalizado, só a postbackUrl recebe o charge.updated com status: "chargeback". O desenho abaixo mostra o caminho de um alerta de pré-chargeback e como marcar o pedido em cada caso.

Exemplos de payload

Envelope padrão, com as chaves de data em snake_case. O exemplo mostra parte do objeto data.

Regras de negócio

Uma cobrança em disputa ainda pode terminar com o valor devolvido ao cliente. Se o pedido é de produto físico ainda não enviado, avalie com a sua operação se o envio deve esperar o resultado.

Implementação recomendada

O desenho abaixo resume a lógica do código: o que fazer com cada aviso e a rotina que detecta a liberação do bloqueio.
Node.js
O charge.updated chega só à postbackUrl, em camelCase e sem id/livemode. Os demais eventos seguem o envelope padrão, em snake_case, e chegam aos endpoints e à postbackUrl. Se a mesma URL está cadastrada nos dois canais, ela recebe cada evento duas vezes: deduplique pelo id do evento.

Erros comuns

Perguntas frequentes

Respondendo ao e-mail do alerta de chargeback ou MED, com as evidências, dentro do prazo indicado. Não existe envio de defesa pela API.
Não. O MED é o pedido de devolução de um Pix feito pela instituição do pagador. O bloqueio cautelar é uma retenção preventiva e curta, feita pela instituição do recebedor quando suspeita de fraude. Na API, os dois aparecem como bloqueio da cobrança (isBlocked).
Não. O MED existe só no Pix. No cartão, o equivalente é o chargeback.
Porque o pagamento aconteceu. O bloqueio só retém o valor enquanto o caso é analisado. Para saber se a cobrança está bloqueada, leia isBlocked.
O pré-chargeback é um alerta recebido antes de o chargeback ser formalizado, e pode vir com o valor já devolvido ao titular. O chargeback é a disputa formal aberta pelo emissor.
Sim. GET /v1/charges aceita status=blocked, status=pre_chargeback e status=chargeback.

Como testar

O reenvio de webhook de teste (POST /v1/charges/{id}/resend-webhook) não aceita pre_chargeback nem chargeback e não simula o bloqueio. Para testar o seu handler, envie ao seu próprio endpoint os payloads de exemplo desta página. Garanta também que o seu endpoint responde 2xx (cenários CHG-08 e CHG-09 do roteiro de homologação).

Veja também

Webhooks de cobrança

Formato do charge.updated e dos demais eventos.

Estorno

Devolução por iniciativa do merchant.

Consultar cobrança

Campos isBlocked, blockedAt e blockedReason.

Status de cobrança

Todos os status e transições.