Disputas - Mecanismo Especial de Devolução (MED)

O MED (Mecanismo Especial de Devolução) é o processo pelo qual um pagador pode solicitar a devolução de um PIX enviado, geralmente por suspeita de fraude ou erro operacional. Quando um MED é aberto contra sua conta, você tem um prazo para contestar ou aceitar a devolução.

Ciclo de Vida

RECEIVED -> CONTESTED -> PENDING_DECISION -> ACCEPTED / REJECTED / CANCELED

Status	Descrição
RECEIVED	MED recebida. Aguardando sua resposta dentro do prazo (`holderAnswerDeadline`).
CONTESTED	Resposta enviada (AGREE ou DISAGREE) com evidências.
PENDING_DECISION	Resposta enviada ao banco, aguardando decisão do regulador.
ACCEPTED	MED aceita. O valor será devolvido ao pagador (total ou parcial).
REJECTED	MED rejeitada. O valor permanece na sua conta.
CANCELED	MED cancelada pelo reclamante ou regulador.

Resultado Final

Quando uma MED é encerrada, o campo result indica o resultado do parceiro bancário:

Result	Descrição
`AGREED`	Banco concordou com a devolução
`DISAGREED`	Banco discordou da devolução

Devoluções Parciais

Uma MED pode resultar em múltiplas devoluções parciais. Cada devolução possui um E2E próprio (código D) e valor. O campo refundedAmount é a soma de todas as devoluções realizadas.

Cenário	Exemplo
Devolução total	`originalAmount: 1000.00`, `refundedAmount: 1000.00`
Devolução parcial	`originalAmount: 1000.00`, `refundedAmount: 300.00`
Sem devolução (sem saldo)	`originalAmount: 1000.00`, `refundedAmount: 0.00`

Recebendo MEDs via Webhook

Quando uma MED é aberta, você recebe um webhook pix.med.opened. Quando atualizada, pix.med.updated.

{
  "type": "pix.med.opened",
  "data": {
    "endToEndId": "E303062942026021812490000005QLMv",
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "status": "DELIVERED",
    "type": "REVERSAL",
    "method": "INVASION",
    "description": "Fui enganado, não recebi o produto contratado",
    "flow": "IN",
    "openedAt": "2026-02-18T19:34:14Z"
  }
}

Histórico de Status

A API mantém um histórico completo de todas as mudanças de status da MED. Cada entrada contém:

{
  "history": [
    { "status": "RECEIVED", "rawStatus": "DELIVERED", "timestamp": "2026-02-18T19:34:14Z", "description": "MED received" },
    { "status": "CONTESTED", "rawStatus": "CONTESTED", "timestamp": "2026-02-19T10:00:00Z", "description": "Answer: DISAGREE" },
    { "status": "PENDING_DECISION", "rawStatus": "ACKNOWLEDGED", "timestamp": "2026-02-20T14:00:00Z", "description": "" },
    { "status": "REJECTED", "rawStatus": "REJECTED", "timestamp": "2026-02-23T09:00:00Z", "description": "" }
  ]
}

Contestando uma MED

Em breve: A contestação via API (envio de resposta e upload de evidências) estará disponível em uma atualização futura. Por enquanto, a contestação deve ser feita diretamente no canal do parceiro bancário.

Listagem de MEDs

GET /v1/backoffice/tenants/{tenantId}/meds

Retorna todas as MEDs do tenant com histórico completo, refunds e campos de controle (holderAnswerStatus, holderAnswerDeadline, result).

Monitoramento de Taxa de MED

GET /v1/backoffice/tenants/{tenantId}/med-stats?days=30

Retorna estatísticas diárias consolidadas:

Campo	Descrição
`pixInCount`	Transações PIX IN naquele dia
`pixInAmount`	Valor total de PIX IN
`medCount`	Número de MEDs para transações daquele dia
`medAmount`	Valor total de MEDs
`quantityRatePercent`	medCount / pixInCount * 100
`amountRatePercent`	medAmount / pixInAmount * 100

Faixas de Referência

Taxa	Status	Descrição
< 0.4%	Verde	Taxa saudável
0.4% - 1.0%	Amarelo	Atenção, monitorar
> 1.0%	Vermelho	Taxa elevada, ações podem ser necessárias

Políticas de MED

Consulte o guia de Políticas e Regras para configurar:

Auto-block: Bloquear saldo automaticamente para MEDs acima de um valor.
Taxa máxima: Limite de proporção MED/PIX-In com ações automáticas.

Ciclo de Vida​

Resultado Final​

Devoluções Parciais​

Recebendo MEDs via Webhook​

Histórico de Status​

Contestando uma MED​

Listagem de MEDs​

Monitoramento de Taxa de MED​

Faixas de Referência​

Políticas de MED​