Como funciona a MED

O MED (Mecanismo Especial de Devolução) é o caminho do PIX para o pagador contestar um pagamento pelo banco dele. Para você, cada contestação vira uma disputa: o valor fica retido, você manda a defesa até o prazo e a decisão diz se o dinheiro fica ou volta.

O ciclo de uma disputa

Status da disputa
StatusO que significaSaldo
OPENAberta, esperando o seu material.O valor contestado sai do disponível e fica retido (até o que o disponível cobre).
UNDER_ANALYSISVocê mandou a primeira evidência; aguardando a decisão.Segue retido.
WONDecidida a favor da empresa.O retido volta ao disponível.
LOSTDecidida a favor do pagador: o valor voltou para ele.Sai o que voltou ao pagador; se for menos que o retido, a sobra volta ao disponível.
CANCELEDEncerrada sem devolução (contestação retirada, aberta por engano).O retido volta ao disponível.
  • Você não abre disputa pela API: quem abre é o banco do pagador, e a plataforma registra.
  • A cobrança contestada fica DISPUTED. Na decisão, volta a PAID ou, se o valor voltou ao pagador, vira PARTIALLY_REFUNDED ou REFUNDED.
  • Contesta-se só o que ainda não tinha voltado ao pagador: numa cobrança já devolvida em parte, a disputa é sobre o resto.
  • Enquanto a disputa está viva, a cobrança não aceita devolução (CHARGE_DISPUTED).

Quanto mais material, mais forte a defesa. A decisão do MED é do banco do pagador: nenhum conjunto de provas garante o resultado.

Eventos

  • dispute.created
  • dispute.updated
  • dispute.closed
  • charge.refunded
  • charge.partially_refunded

dispute.created na abertura, com o valor já retido. dispute.updated quando o status ou o prazo muda com a disputa viva (por exemplo, ao ir para análise depois da sua primeira evidência). dispute.closed na decisão, com outcome. Disputa perdida também avisa a cobrança: charge.refunded ou charge.partially_refunded.

O recurso dispute

  • id · codetextosempreId (dsp_…) e o código legível que aparece no painel (DS-0019).
  • typetextosempreSempre "MED".
  • statustextosempreOPEN, UNDER_ANALYSIS, WON, LOST ou CANCELED.
  • chargeIdtextosempreA cobrança contestada.
  • amounttextosempreValor contestado.
  • heldAmounttextosempreQuanto ficou retido do seu disponível (pode ser menos que amount, se o disponível não cobria).
  • currency · reasontextosempreMoeda e o motivo informado na abertura.
  • evidenceDueAtdatasempreAté quando você envia evidências, defesa e explicação.
  • outcome · decisionNotetextopode ser nullWON, LOST ou CANCELED e a nota da decisão, quando decidida; null enquanto viva.
  • returnedAmounttextopode ser nullSó em LOST: o que de fato voltou ao pagador (pode ser menos que o contestado).
  • providerProtocol · providerStatus · providerDueAttextopode ser nullQuando a disputa vem do provedor: o protocolo, a situação lá e o prazo dele (o seu evidenceDueAt termina antes).
  • openedAt · closedAtdatapode ser nullAbertura e decisão.

GET /v1/disputes/:id traz também o que você já mandou: evidence (só os dados dos arquivos, nunca o conteúdo), comment, defense (a versão que vale), evidenceOpen (ainda dá para enviar), evidenceLimit e strength, a força da defesa (score de 0 a 100, level e a lista do que falta). Os webhooks dispute.* trazem só o recurso da tabela.

Rotas de leitura

Rotas de leitura de disputas
RotaO que devolve
GET /v1/disputesDisputas do ambiente, mais recentes primeiro, com cursor. Filtros status e chargeId.
GET /v1/disputes/:idUma disputa, com evidências, explicação, defesa e força.
GET /v1/charges/:id/disputesAs disputas de uma cobrança, da mais antiga para a mais nova (sem cursor).

Ler pede disputes em read; responder pede write. Chave criada antes deste recurso existir fica com none: crie outra com o escopo. Para responder, veja Enviar defesa.