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

Endpoints REST de MED temporariamente offline

Os webhooks de MED estão ativos: você recebe pix.med.opened e pix.med.updated normalmente quando uma disputa é aberta ou muda de status (ver Webhooks).

Todos os endpoints REST do módulo — consulta (GET /v1/accounts/{accountId}/pix/med), contestação (answer, decide, evidence/*) e também a listagem e as estatísticas por tenant (/v1/backoffice/tenants/{tenantId}/meds e /med-stats) — respondem HTTP 503 com errorCode: "service_temporarily_unavailable" durante a migração de liquidante. A documentação abaixo descreve o contrato desses endpoints, que volta a valer quando forem reativados.

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

OPEN -> PENDING_DECISION -> ACCEPTED / REJECTED / CANCELED

O webhook usa um vocabulário fechado de cinco valores em data.status. Status crus do liquidante nunca são propagados: o que não casa com a tabela abaixo vira PENDING_DECISION.

Status	Descrição
OPEN	MED aberta contra a sua conta. Aguardando resposta dentro do prazo.
PENDING_DECISION	Resposta enviada ao banco, aguardando decisão do regulador. Também é o valor usado quando o liquidante manda um status fora do vocabulário.
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.

O estado CONTESTED e o histórico detalhado pertencem ao contrato dos endpoints REST (hoje em 503) — não aparecem nos webhooks.

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.

{
  "id": "pix-med-opened-204cc938-da3d-4f04-baf3-0b2e6a2f1283",
  "type": "pix.med.opened",
  "occurredAt": "2026-02-18T19:34:14.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "773107de-...",
  "data": {
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "tenantId": "tenant-suaempresa",
    "accountId": "773107de-...",
    "originalEndToEnd": "E303062942026021812490000005QLMv",
    "amount": 1000.00,
    "reasonCode": "FRAUD",
    "claimMessage": "Fui enganado, não recebi o produto contratado",
    "openedAtIso": "2026-02-18T19:34:14.000000000Z",
    "status": "OPEN"
  }
}

O pix.med.updated traz o mesmo conjunto de campos, sem claimMessage e openedAtIso, com status refletindo a transição.

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

A contestação via API (envio de resposta e upload de evidências) usa os endpoints POST /v1/accounts/{accountId}/pix/med/{medId}/answer, /decide e /evidence/* — todos em 503 hoje, conforme o aviso no topo desta página. Enquanto isso, a contestação deve ser feita diretamente no canal do parceiro bancário.

Consulta e listagem de MEDs

Por conta:

GET /v1/accounts/{accountId}/pix/med

Por tenant (backoffice):

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

Quando reativadas, retornam as MEDs 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

As faixas abaixo são referência operacional (usadas no painel e no acompanhamento comercial), não um comportamento da API: nenhum código de erro ou bloqueio decorre automaticamente delas. Ações automáticas por taxa são configuradas em Políticas e Regras.

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​

Consulta e listagem de MEDs​

Monitoramento de Taxa de MED​

Faixas de Referência​

Políticas de MED​