Listar MED

Lista los procesos MED (Mecanismo Especial de Devolucion) asociados a la cuenta.

El MED es un mecanismo del Banco Central para recuperacion de valores en casos de fraude o falla operacional en el sistema PIX.

Endpoint

GET /api/external/med

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
X-Key-Case	String	No	Defina como camelCase para recibir los campos de la respuesta en camelCase (default es snake_case)

Permisos

Este endpoint requiere el permiso payment:read en la API Key. Claves sin ese permiso reciben HTTP 403.

Ejemplo

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

Sin paginacion nativa

Este endpoint consulta al provider OnZ/BACEN en tiempo real y no acepta parametros de paginacion (page/per_page/limit). Todos los MEDs vinculados a la entidad son retornados en una unica respuesta. Para grandes volumenes, filtre localmente en su sistema despues de recibir el array.

Respuesta de Exito (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	Descripcion
worked	Boolean	true indica exito en la operacion
meds	Array	Lista de procesos MED
meds[].id	String	Identificador unico del MED
meds[].type	String	Tipo del MED (vea tabla abajo)
meds[].status	String	Status actual del proceso
meds[].amount	Integer	Valor en unidades base (÷ 10.000 para reales). 50000 = R$ 5,00
meds[].original_end_to_end_id	String	E2E de la transaccion PIX original
meds[].created_at	String	Fecha de apertura (ISO 8601)

Tipos de MED

Tipo	Descripcion
REFUND_REQUEST	Solicitud de devolucion (fraude, estafa o acuerdo)
REFUND_CANCELLED	Cancelacion de solicitud de devolucion anterior

Status del MED

Valores retornados por el provider PIX (OnZ/BACEN) en UPPERCASE. La API repasa el valor tal como recibido — no hay normalizacion.

Status	Descripcion	Decision final
ACKNOWLEDGED	MED recibido y reconocido por el participante, en analisis	No — aguarda defensa o plazo
CLOSED	MED finalizado por el participante	Si — vea analysisResult en med-detail para distinguir AGREED (devolucion ejecutada) de DISAGREED (defensa aceptada, sin devolucion)
CANCELLED	MED cancelado por el solicitante antes del analisis	Si — ningun valor fue bloqueado ni devuelto

El status es uppercase

Los status del MED siempre son retornados en MAYUSCULAS. Si su filtro espera minusculas (pending/accepted/closed), el no va a encontrar ninguna fila. Esta es una diferencia consciente en relacion a los status de transaccion PIX (lowercase) — MED sigue la convencion BACEN original.

Correlacion con transaccion original

Use el campo original_end_to_end_id para localizar la transaccion PIX original que motivo el MED. Consulte via GET /api/external/transactions/:id o GET /api/external/transactions/ref/:external_id si usted almaceno el external_id.

Retorno en ambientes dev/homologacion

Este endpoint consulta al provider OnZ directamente — no lee de tabla local. En dev/homologacion puede retornar array vacio si el proveedor OnZ no tiene MEDs de prueba para la entidad configurada. En produccion, retorna la lista real de procesos MED de su cuenta conforme repasada por el OnZ/BACEN.

Fallas en el proveedor retornan array vacio

Si hay indisponibilidad temporal del proveedor OnZ, el endpoint retorna {"worked": true, "meds": []} (silenciosamente, sin 5xx). Si usted recibe array vacio de forma persistente mientras espera MEDs, consulte al soporte para verificar si hay indisponibilidad del proveedor.

Respuesta de Exito -- Sin MEDs (200)

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

Respuesta de Error (401)

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

Bloqueo de valores en disputa

Cuando una infraccion REFUND_REQUEST es registrada en ACKNOWLEDGED con valor >R$ 1.000,00 (limite configurable por cuenta o merchant via med_configurations.min_threshold_amount), el backend crea un bloqueo cautelar en TigerBeetle (med_cautelar_blocks row + phantom hold TB code 1032). El valor disputado queda:

• Descontado del available retornado por Saldo
• Sumado en pending
• Preservado en el balance (saldo seguro) hasta decision final

Infracciones con valor ≤R$ 1.000,00 o con e2e_id inexistente en sus transactions reciben auto-deny automatico (cierre con AnalysisResult=DISAGREED) sin crear bloqueo cautelar.

Cuando el MED es resuelto (CLOSED), el bloqueo es liberado:

• AnalysisResult=AGREED → valor transferido al solicitante (PIX devolucion via PACS.004, E2E prefijo D)
• AnalysisResult=DISAGREED → valor vuelve al available del merchant

Suscriba los webhooks pix.infraction.created, pix.refund.requested y pix.infraction.resolved para notificacion en tiempo real de cada etapa. Ver Infracciones (flujo completo) para entender el ciclo end-to-end.

Auto-expiracion: el worker Fluxiq.Workers.MedDefenseExpiration (cron */5 * * * *) auto-acepta bloqueos con deadline en los proximos 30 min cuya defensa aun no fue enviada — esto evita multa regulatoria BACEN por no responder en el plazo. Vea seccion "Plazos" en Infracciones.