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 | O que significa | Saldo |
|---|---|---|
OPEN | Aberta, esperando o seu material. | O valor contestado sai do disponível e fica retido (até o que o disponível cobre). |
UNDER_ANALYSIS | Você mandou a primeira evidência; aguardando a decisão. | Segue retido. |
WON | Decidida a favor da empresa. | O retido volta ao disponível. |
LOST | Decidida 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. |
CANCELED | Encerrada 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 aPAIDou, se o valor voltou ao pagador, viraPARTIALLY_REFUNDEDouREFUNDED. - 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.createddispute.updateddispute.closedcharge.refundedcharge.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
| Rota | O que devolve |
|---|---|
GET /v1/disputes | Disputas do ambiente, mais recentes primeiro, com cursor. Filtros status e chargeId. |
GET /v1/disputes/:id | Uma disputa, com evidências, explicação, defesa e força. |
GET /v1/charges/:id/disputes | As 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.