Detalhes MED

Consulta os detalhes completos de um processo MED (Mecanismo Especial de Devolução) específico.

Endpoint

GET /api/external/med/:id

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)

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
id	String	Sim	Identificador do processo MED

Exemplo

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

Resposta de Sucesso (200)

{
  "worked": true,
  "med": {
    "id": "MED20260307001",
    "type": "REFUND_REQUEST",
    "status": "ACKNOWLEDGED",
    "amount": 50000,
    "original_end_to_end_id": "E37839059202603071530000001",
    "reason": "Fraude reportada pelo pagador",
    "created_at": "2026-03-07T18:00:00Z"
  }
}

Status em UPPERCASE

Valores possíveis: ACKNOWLEDGED, CLOSED, CANCELLED. Repassados tal como recebidos do provider PIX (OnZ/BACEN) — sem normalização. Ver med-list para detalhes.

Campo	Tipo	Descrição
worked	Boolean	true indica sucesso na operação
med.id	String	Identificador único do MED
med.type	String	Tipo: REFUND_REQUEST ou REFUND_CANCELLED
med.status	String	Status atual do processo (ACKNOWLEDGED, CLOSED, CANCELLED)
med.amount	Integer	Valor em unidades base (÷ 10.000 para reais). 50000 = R$ 5,00
med.original_end_to_end_id	String	E2E da transação PIX original. Use para cruzar com GET /transactions/ref/:external_id
med.reason	String	Motivo informado pelo solicitante (texto livre). null se não disponível
med.created_at	String	Data de abertura (ISO 8601 UTC)

Campos adicionais não expostos via External API

O provedor OnZ/BACEN retorna mais campos do que os expostos por este endpoint. Os campos filtrados deliberadamente no serializer incluem:

Campo (OnZ)	Descrição	Onde obter hoje
analysisResult	Decisão final: AGREED ou DISAGREED	Webhook pix.infraction.resolved
analysisDetails	Justificativa da decisão	Webhook pix.infraction.resolved
infractionType	REFUND_REQUEST ou REFUND_CANCELLED	Já exposto em med.type
fraudType	SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER	Webhook pix.refund.requested (campo fraud_category)
situationType	Tipo de situação envolvida (BACEN taxonomy)	Merchant portal (/compliance) — não disponível via External API
defenseDeadline	Prazo BACEN para submissão de defesa	Webhook pix.infraction.created

Esta omissão é deliberada (gap conhecido). Se você precisa consumir esses campos programaticamente, contate compliance@owem.com.br — ou use os webhooks listados, que sempre trazem os campos relevantes no momento do evento.

Ver Infrações (fluxo completo) para entender a relação entre MED e Infrações.

Valor em subcentavos, não em BRL

O campo amount é em subcentavos (1 BRL = 10.000 subcentavos). Valor 50000 = R$ 5,00 — não R$ 50.000. Nunca multiplique por 100 nem use float.

Resposta de Erro (404)

{
  "worked": false,
  "errors": {
    "not_found": "MED não encontrado"
  }
}

404 pode indicar erro transitório

Se o MED existe em outro canal (webhook, listagem anterior) mas retorna 404 nesta consulta, pode ser falha transitória do provedor OnZ. Tente novamente em alguns segundos. Se persistir após 5 min, contate o suporte.

O backend converte todos os erros do provedor (incluindo timeouts e erros de rede) em HTTP 404 com detail: "MED nao encontrado". Para distinguir "não existe" de "falha transitória", consulte primeiro o endpoint Listar MED — se o ID aparece na lista mas o detail retorna 404, é transitório.

Resposta de Erro (401)

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

Acompanhamento em tempo real (webhooks)

Os eventos de webhook pix.refund.requested e pix.refund.completed SÃO disparados automaticamente pelo backend a partir de abril/2026. Recomendado assinar esses webhooks para não depender de polling. Polling em GET /med/:id ou GET /med continua funcionando como alternativa.