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

Sin paginacion nativa

Este endpoint consulta al provider PIX/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": "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	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 (PIX/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 PIX directamente - no lee de tabla local. En dev/homologacion puede retornar array vacio si el proveedor PIX 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 PIX/BACEN.

Fallas en el proveedor retornan array vacio

Si hay indisponibilidad temporal del proveedor PIX, 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>"
  }
}

Valores en disputa

Cuando un MED requiere analisis, el valor disputado puede quedar temporalmente reservado y aparecer en pending hasta la decision final.

Cuando el MED es resuelto (CLOSED):

• AnalysisResult=AGREED indica disputa aceptada y devolucion ejecutada.
• AnalysisResult=DISAGREED indica disputa rechazada o defensa aceptada, sin devolucion.

Suscriba los webhooks pix.infraction.created, pix.refund.requested, pix.infraction.defense_submitted y pix.infraction.resolved. Para responder un MED por API, use POST /api/external/med/:id/defense con payment:write. Ver Infracciones.