Listar MED

Lista os processos MED (Mecanismo Especial de Devolução) associados à conta.

O MED é um mecanismo do Banco Central para recuperação de valores em casos de fraude ou falha operacional no sistema PIX.

Endpoint

GET /api/external/med

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Não	Defina como camelCase para receber os campos da resposta em camelCase (padrão é snake_case)

Permissões

Este endpoint requer a permissão payment:read na API Key. Chaves sem essa permissão recebem HTTP 403.

Exemplo

curl -X GET https://api.owem.com.br/api/external/med \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Sem paginação nativa

Este endpoint consulta o provider OnZ/BACEN em tempo real e não aceita parâmetros de paginação (page/per_page/limit). Todos os MEDs vinculados à entidade são retornados em uma única resposta. Para grandes volumes, filtre localmente no seu sistema após receber o array.

Resposta de Sucesso (200)

{
  "worked": true,
  "meds": [
    {
      "id": "MED20260307001",
      "type": "REFUND_REQUEST",
      "status": "ACKNOWLEDGED",
      "amount": 50000,
      "original_end_to_end_id": "E37839059202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E37839059202603051200000003",
      "created_at": "2026-03-05T14:30:00Z"
    }
  ]
}

Campo	Tipo	Descrição
worked	Boolean	true indica sucesso na operação
meds	Array	Lista de processos MED
meds[].id	String	Identificador único do MED
meds[].type	String	Tipo do MED (veja tabela abaixo)
meds[].status	String	Status atual do processo
meds[].amount	Integer	Valor em unidades base (÷ 10.000 para reais). 50000 = R$ 5,00
meds[].original_end_to_end_id	String	E2E da transação PIX original
meds[].created_at	String	Data de abertura (ISO 8601)

Tipos de MED

Tipo	Descrição
REFUND_REQUEST	Solicitação de devolução (fraude, golpe ou acordo)
REFUND_CANCELLED	Cancelamento de solicitação de devolução anterior

Status do MED

Valores retornados pelo provider PIX (OnZ/BACEN) em UPPERCASE. A API repassa o valor tal como recebido — não há normalização.

Status	Descrição	Decisão final
ACKNOWLEDGED	MED recebido e reconhecido pelo participante, em análise	Não — aguarda defesa ou prazo
CLOSED	MED finalizado pelo participante	Sim — veja analysisResult em med-detail para distinguir AGREED (devolução executada) de DISAGREED (defesa aceita, sem devolução)
CANCELLED	MED cancelado pelo solicitante antes da análise	Sim — nenhum valor foi bloqueado nem devolvido

Status é uppercase

Os status do MED são sempre retornados em MAIÚSCULAS. Se o seu filtro espera minúsculas (pending/accepted/closed), ele não vai encontrar nenhuma linha. Esta é uma diferença consciente em relação aos status de transação PIX (lowercase) — MED segue a convenção BACEN original.

Correlação com transação original

Use o campo original_end_to_end_id para localizar a transação PIX original que motivou o MED. Consulte via GET /api/external/transactions/:id ou GET /api/external/transactions/ref/:external_id se você armazenou o external_id.

Retorno em ambientes dev/homologação

Este endpoint consulta o provider OnZ diretamente — não lê de tabela local. Em dev/homologação pode retornar array vazio se o provedor OnZ não tiver MEDs de teste para a entidade configurada. Em produção, retorna a lista real de processos MED da sua conta conforme repassada pelo OnZ/BACEN.

Falhas no provedor retornam array vazio

Se houver indisponibilidade temporária do provedor OnZ, o endpoint retorna {"worked": true, "meds": []} (silenciosamente, sem 5xx). Se você recebe array vazio de forma persistente enquanto espera MEDs, consulte o suporte para verificar se há indisponibilidade do provedor.

Resposta de Sucesso -- Sem MEDs (200)

{
  "worked": true,
  "meds": []
}

Resposta de Erro (401)

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

Bloqueio de valores em disputa

Quando uma infração REFUND_REQUEST é registrada em ACKNOWLEDGED com valor >R$ 1.000,00 (limiar configurável por conta ou merchant via med_configurations.min_threshold_amount), o backend cria um bloqueio cautelar em TigerBeetle (med_cautelar_blocks row + phantom hold TB code 1032). O valor disputado fica:

• Descontado do available retornado por Saldo
• Somado em pending
• Preservado no balance (saldo seguro) até decisão final

Infrações com valor ≤R$ 1.000,00 ou com e2e_id inexistente nas suas transactions recebem auto-deny automático (fechamento com AnalysisResult=DISAGREED) sem criar bloqueio cautelar.

Quando o MED é resolvido (CLOSED), o bloqueio é liberado:

• AnalysisResult=AGREED → valor transferido para o solicitante (PIX devolução via PACS.004, E2E prefixo D)
• AnalysisResult=DISAGREED → valor retorna para o available do merchant

Assine os webhooks pix.infraction.created, pix.refund.requested e pix.infraction.resolved para notificação em tempo real de cada etapa. Ver Infrações (fluxo completo) para entender o ciclo end-to-end.

Auto-expiração: o worker Fluxiq.Workers.MedDefenseExpiration (cron */5 * * * *) auto-aceita bloqueios com deadline nos próximos 30 min cuja defesa ainda não foi submetida — isso evita multa regulatória BACEN por não responder no prazo. Ver seção "Prazos" em Infrações.