PIX disputes (MED)

MED (Mecanismo Especial de Devolução) é o mecanismo do Banco Central pra contestar uma transação PIX com indício de fraude — quando alguém abre um MED contra um pagamento recebido pela sua conta, o valor é bloqueado preventivamente até a disputa ser resolvida.

Nota

Diferente do resto desta documentação, uma disputa nunca é criada nem respondida pela API pública — ela chega por webhook (quando aberta) e é resolvida pelo Backoffice, por um admin. Esta página existe pra você saber o que esperar quando isso acontecer com uma venda sua.

O que acontece quando um MED é aberto

O provider financeiro notifica o Gateway de que uma disputa foi aberta contra um pagamento seu.
O valor da transação é bloqueado imediatamente na sua conta (sai do saldo disponível, some do netInCents do saldo — ver blockedInCents).
Você recebe o evento pix.dispute_opened no seu endpoint de webhook, se estiver inscrito nele.
Um admin analisa e responde a disputa pelo Backoffice — aceitando (fraude confirmada) ou recusando (sem indício de fraude).
Você recebe pix.dispute_resolved com o resultado.

Webhook — disputa aberta

{
  "id": "3f9a...",
  "type": "pix.dispute_opened",
  "tenantId": "961c52b2-...",
  "merchantId": "0d303c3b-...",
  "occurredAt": "2026-09-16T12:04:11.000Z",
  "pixInfractionId": "7c21...",
  "providerInfractionId": "31afecd6-...",
  "endToEndId": "E00360305202609152015b5955bb1ad4",
  "infractionType": "REFUND_REQUEST",
  "infractionSituationType": "RECEIVED",
  "amountInCents": 1990,
  "checkoutSessionId": "cf810b10-..."
}

type no topo é sempre pix.dispute_opened (o tipo do EVENTO, envelope comum a todo webhook — ver Webhooks); o tipo/motivo da DISPUTA em si vem em campos com nome diferente (infractionType/infractionSituationType), pra nunca colidir com o type do envelope.

Campo	Conteúdo
`providerInfractionId`	Id da disputa no provider — referência pra acompanhar no painel dele, se aplicável.
`endToEndId`	Identificador PIX da transação contestada.
`infractionType` / `infractionSituationType`	Categoria/motivo relatados pelo provider — nem todo provider preenche os dois (ex.: a Nuvende só confirma o código do alerta, sem um motivo textual).
`amountInCents`	Valor bloqueado — sempre o valor da transação original.
`checkoutSessionId`	A venda contestada, se ainda identificável.

Webhook — disputa resolvida

{
  "id": "8b12...",
  "type": "pix.dispute_resolved",
  "tenantId": "961c52b2-...",
  "merchantId": "0d303c3b-...",
  "occurredAt": "2026-09-17T09:30:00.000Z",
  "pixInfractionId": "7c21...",
  "providerInfractionId": "31afecd6-...",
  "endToEndId": "E00360305202609152015b5955bb1ad4",
  "outcome": "rejected",
  "amountInCents": 1990
}

outcome é accepted (fraude confirmada — o valor não volta pra sua conta, é transferido pro reclamante) ou rejected (sem indício de fraude — o valor bloqueado volta integralmente pro seu saldo).

Atenção

Um MED aceito é definitivo — o valor bloqueado não retorna à sua conta de jeito nenhum depois dessa decisão. Só se aplica quando há indício real de fraude na transação original.

Acompanhando pelo saldo

Enquanto uma disputa está aberta, o valor bloqueado aparece em blockedInCents no endpoint de saldo — some de lá assim que ela é resolvida (voltando pro netInCents, se recusada; saindo de vez, se aceita). O extrato mostra o lançamento de bloqueio e o de liberação/perda como entradas separadas, com a descrição indicando o motivo.