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.minhakonta.com/api/external/med \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Sem paginação nativa

Este endpoint consulta o provider PIX/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": "E04838403202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E04838403202603051200000003",
      "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 (PIX/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 PIX diretamente - não lê de tabela local. Em dev/homologação pode retornar array vazio se o provedor PIX 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 PIX/BACEN.

Falhas no provedor retornam array vazio

Se houver indisponibilidade temporária do provedor PIX, 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>"
  }
}

Valores em disputa

Quando um MED exige análise, o valor disputado pode ficar temporariamente reservado e aparecer em pending até a decisão final.

Quando o MED é resolvido (CLOSED):

• AnalysisResult=AGREED indica contestação aceita e devolução executada.
• AnalysisResult=DISAGREED indica contestação rejeitada ou defesa aceita, sem devolução.

Assine os webhooks pix.infraction.created, pix.refund.requested, pix.infraction.defense_submitted e pix.infraction.resolved para acompanhar cada etapa. Para responder um MED pela API, use POST /api/external/med/:id/defense com permissão payment:write. Ver Infrações.