Disputas e MED (contestação Pix)

Um pagamento Pix pode ser contestado depois de pago. No Pix, o canal para isso é o MED (Mecanismo Especial de Devolução) do BACEN: o pagador pede ao banco dele a devolução de uma transação que alega ter sido fraude, golpe ou erro. Quando um MED é aberto contra uma cobrança sua, a Liqfy detecta, retém o valor da sua conta enquanto o caso corre e te avisa — para que você não descubra o prejuízo só no fim do mês.

Isto é diferente de um estorno (refund), que é uma devolução que você decide fazer. O MED é iniciado pelo pagador, do lado do banco dele.

Hoje só o provedor MagenPay entrega o MED automaticamente para a Liqfy. Outros provedores serão ligados a este mesmo fluxo conforme forem integrados — do seu lado a mecânica é a mesma, independentemente do provedor por trás.

#O ciclo de vida, de relance

        cobrança paid
             │
   MED aberto pelo pagador (webhook do provedor)
             │
             ▼
     status "disputed"  ── valor retido da sua conta, estorno bloqueado
             │
   ┌─────────┼───────────────────────────┐
   ▼         ▼                           ▼
 ganho     perdido                   retirado
 (won)     (lost)                    (canceled)
   │         │                           │
   ▼         ▼                           ▼
 volta a   permanece "disputed"      volta a
  "paid"   (tratativa manual)         "paid"
 valor     valor NÃO devolvido       valor
 devolvido                           devolvido

#O que acontece quando um MED abre

1. A cobrança vira disputed. O status público da cobrança (vocabulário de status) passa de paid para disputed. Uma cobrança disputed não pode ser estornada — o estorno fica bloqueado enquanto o caso está aberto, para evitar a devolução em dobro (estorno seu + MED executado pelo banco).
2. A Liqfy retém o valor da sua conta. O valor da cobrança é debitado do seu saldo operacional (podendo deixá-lo negativo) e fica retido como reserva enquanto o caso corre. Se você ganhar, ele volta; se perder, ele já estava reservado.
3. Você é notificado. Enviamos um e-mail (med-opened) e o caso aparece no painel de Disputas do seu dashboard, com o valor, o motivo alegado e a identidade de quem abriu o MED (nome/documento do pagador, quando o provedor informa), para você conseguir entrar em contato.
4. Nenhum webhook charge.* é disparado para a transição de disputa. Um MED não é uma "falha" da cobrança (ela foi paga), então não emitimos charge.failed para não te induzir a erro. Detecte a disputa pelo e-mail, pelo painel, ou relendo a cobrança (GET /v1/charges/{id} → status: "disputed").

#Estados do caso

O caso de disputa tem o seu próprio ciclo, visível no painel de Disputas:

#Contestar (appeal) e anexar evidência

No painel de Disputas você pode contestar um MED OPEN e anexar evidência (nota fiscal, comprovante de entrega, conversas — o que sustente que a cobrança foi legítima).

Importante — o que a contestação é, e o que ela não é. Contestar não é uma submissão automática ao BACEN nem ao banco do reclamante. Hoje a Liqfy não tem um canal formal de defesa junto à MagenPay (a API de infração vive na infra Voluti upstream, sem credencial disponível). O appeal e a evidência que você envia são registrados internamente, para a equipe da Liqfy avaliar o caso e conduzir a tratativa manual. O desfecho oficial vem do provedor/BACEN, e chega até nós pelo próprio webhook de MED.

#Os desfechos

• Ganho (disagreed) — o julgamento foi a seu favor. A cobrança volta a paid e o valor retido é devolvido à sua conta. Enviamos o e-mail de MED resolvido (med-resolved, outcome: won).
• Retirado (canceled) — o pagador desistiu da reclamação. Tratado como um ganho: a cobrança volta a paid e o valor é devolvido.
• Perdido (agreed) — a devolução foi executada de verdade; o dinheiro saiu (ou sairá). A Liqfy nunca fecha esse caso automaticamente — a cobrança permanece disputed e a equipe conduz a tratativa manual. O valor não é devolvido a você.

#Campos de metadata da transação

A partir da ingestão de MED, a transação passa a carregar dois blocos informativos no metadata, que aparecem no objeto metadata da cobrança e no detalhe da transação no admin. São informativos e não-autoritativos: espelham o que o provedor reportou, são somente-leitura e podem mudar a cada evento do caso. Não construa lógica de dinheiro em cima deles — a fonte da verdade é o status da cobrança e o painel de Disputas.

#metadata.med — presente numa cobrança em disputa

#metadata.failure — presente numa cobrança expired / cancelled / failed

#Referência técnica

• O formato do webhook pixInfraction da MagenPay e como a Liqfy o correlaciona: MagenPay — webhooks.
• Estorno voluntário (diferente de MED): veja a pergunta sobre estorno em Pix e a Referência da API.