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.
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.
- 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.
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}.
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.
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
- charge.blocked
- charge.updated (bloqueio)
- charge.pre_chargeback
Envelope padrão, com as chaves de
data em snake_case. O exemplo mostra parte do objeto data.Regras de negócio
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
Como envio a defesa?
Como envio a defesa?
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.
MED e bloqueio cautelar são a mesma coisa?
MED e bloqueio cautelar são a mesma coisa?
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).Existe MED no cartão?
Existe MED no cartão?
Não. O MED existe só no Pix. No cartão, o equivalente é o chargeback.
Por que o status continua paid durante o bloqueio?
Por que o status continua paid durante o bloqueio?
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.Qual a diferença entre pré-chargeback e chargeback?
Qual a diferença entre pré-chargeback e chargeback?
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.
Posso filtrar as cobranças em disputa?
Posso filtrar as cobranças em disputa?
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.

