MED 2.0 (Mecanismo Especial de Devolución) es el mecanismo mejorado de BACEN para recuperar fondos en casos de fraude, estafas y errores operativos. MED 1.0 maneja disputas de una sola transacción a través de reportes de infracción. MED 2.0 introduce un flujo de Recuperación de Fondos que rastrea cómo se movieron los fondos fraudulentos entre múltiples cuentas. El flujo coordina el bloqueo, el análisis y los reembolsos entre las instituciones participantes. El Plugin Pix Indirecto (BTG) expone el ciclo de vida completo de Recuperación de Fondos como endpoints REST. También envía eventos de webhook, para que tu sistema se mantenga sincronizado con cada cambio de estado.

MED 2.0 es un requisito de BACEN para los participantes de Pix. El plugin implementa el flujo de Recuperación de Fondos, para que puedas cumplir este requisito a través de tu conexión indirecta con BTG.

Conceptos

Término	Definición
Recuperación de fondos	El proceso de MED 2.0 que recupera fondos entre múltiples cuentas tras un fraude reportado
Grafo de rastreo	Una representación de cómo fluyeron los fondos entre cuentas, personas y transacciones
Transacción raíz	La transacción Pix fraudulenta original que inicia la recuperación
Reporte de infracción	Un reporte de una transacción fraudulenta/problemática, ahora vinculado a su Recuperación de Fondos principal
Solicitud de reembolso	Una solicitud para devolver los fondos bloqueados a la víctima

Ciclo de vida y estado

Una Recuperación de Fondos avanza por los siguientes estados:

Estado	Descripción
`CREATED`	Estado inicial tras la creación
`TRACKED`	Grafo de rastreo generado
`AWAITING_ANALYSIS`	Flujo de bloqueo iniciado, a la espera del análisis del reporte de infracción
`ANALYSED`	Todos los reportes de infracción analizados, listo para el reembolso
`REFUNDING`	Solicitudes de reembolso iniciadas
`COMPLETED`	Todos los reembolsos completados
`CANCELLED`	Recuperación cancelada (solo permitido antes de que comiencen los reembolsos)

Endpoints

Todos los endpoints de Recuperación de Fondos viven bajo el dominio DICT y requieren el encabezado X-Account-Id.

Método	Endpoint	Descripción
`POST`	`/v1/dict/funds-recoveries`	Crear una recuperación de fondos
`GET`	`/v1/dict/funds-recoveries/{id}`	Consultar una recuperación de fondos
`PATCH`	`/v1/dict/funds-recoveries/{id}`	Actualizar el tipo de situación y la información de contacto
`POST`	`/v1/dict/funds-recoveries/{id}/cancel`	Cancelar (antes de que comiencen los reembolsos)
`GET`	`/v1/dict/funds-recoveries/{id}/tracking-graph`	Ver el grafo de rastreo
`GET`	`/v1/dict/funds-recoveries/{id}/infraction-reports`	Listar los reportes de infracción vinculados
`POST`	`/v1/dict/funds-recoveries/{id}/refund`	Solicitar reembolsos (el estado debe ser `ANALYSED`)
`GET`	`/v1/dict/funds-recoveries/{id}/refunds`	Listar las solicitudes de reembolso

Crear una recuperación de fondos

POST /v1/dict/funds-recoveries
{
  "rootTransactionId": "E9999901012341234123412345678900",
  "situationType": "SCAM",
  "contactInformation": {
    "email": "fraud-ops@example.com",
    "phone": "+5511999999999"
  },
  "reportDetails": "Customer reported unauthorized Pix transfer",
  "trackingGraphParameters": {
    "minTransactionAmount": "10.00",
    "maxTransactions": 100,
    "hopWindow": "PT24H",
    "maxHops": 5
  }
}

Reglas de validación

Campo	Requisito
`rootTransactionId`	Requerido, 32 caracteres alfanuméricos
`situationType`	Requerido — uno de `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`, `UNKNOWN`
`contactInformation`	Requerido — objeto con `email` y/o `phone`
`trackingGraphParameters.minTransactionAmount`	Opcional, decimal positivo
`trackingGraphParameters.maxTransactions`	Opcional, 1–1000
`trackingGraphParameters.hopWindow`	Opcional, duración ISO 8601 (p. ej. `PT24H`)
`trackingGraphParameters.maxHops`	Opcional, 1–10

Una llamada exitosa devuelve HTTP 201. La respuesta contiene la nueva recuperación de fondos y sus datos del grafo de rastreo. El plugin persiste el registro localmente con estado CREATED.

Grafo de rastreo

El plugin obtiene el grafo de rastreo fresco de BTG en cada llamada. El grafo no tiene estado local. Lista las personas, cuentas y transacciones del flujo del fraude, con el monto reembolsable de cada transacción.

GET /v1/dict/funds-recoveries/{id}/tracking-graph

La respuesta incluye:

parameters — los parámetros de generación del grafo
persons[] — personas naturales y jurídicas involucradas
accounts[] — cuentas en el flujo con los ISPBs de sus participantes
transactions[] — transacciones Pix con montos y montos reembolsables

Solicitar reembolsos

Una vez que la recuperación alcanza ANALYSED, solicita la devolución de los fondos bloqueados:

POST /v1/dict/funds-recoveries/{id}/refund

El plugin llama a BTG, transiciona la recuperación a REFUNDING y devuelve HTTP 200. Rastrea los estados de reembolso individuales con Listar reembolsos.

Encabezado X-Purpose (transferencias MED 2.0)

Las transferencias de reembolso de MED 2.0 deben llevar un propósito de transacción. El endpoint de cashout acepta un encabezado opcional X-Purpose que el plugin mapea al transactionType de BTG.

POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND

Valor	Descripción	`transactionType` de BTG
`TRANSFER`	Transferencia Pix estándar (por defecto cuando el encabezado se omite)	`TRANSFER`
`INSTANT_PAYMENT_REFUND`	Transferencia de reembolso de MED 2.0	`INSTANT_PAYMENT_REFUND`

Actualmente solo se admiten TRANSFER e INSTANT_PAYMENT_REFUND. Los valores CHANGE, WITHDRAWAL, REFUND_AUTOMATIC_PIX e INSTALLMENT_PIX devuelven HTTP 400 con el error PIX-0429 (Unsupported Purpose).

Las respuestas de transferencia también incluyen el valor purpose (Consultar una transferencia Pix y los endpoints de listado). Los registros existentes usan TRANSFER por defecto.

Campos de correlación

Dos entidades existentes ahora incluyen un campo fundsRecoveryId que vincula una disputa con su recuperación principal:

Reportes de infracción — Consultar un reporte de infracción y el endpoint de listado
Solicitudes de reembolso — Consultar una solicitud de reembolso y el endpoint de listado

Los registros creados fuera del flujo de MED 2.0 no incluyen este campo.

Webhooks

Dos webhooks entrantes de BTG impulsan el flujo de Recuperación de Fondos. Cada uno produce un evento saliente correspondiente hacia tu sistema:

`entityType` saliente	Disparador	Comportamiento
`FUNDS_RECOVERY`	webhook `FUNDS_RECOVERY` de BTG	El plugin actualiza el registro local, luego notifica a tu sistema con la entidad completa
`FUNDS_RECOVERY_EVENTS`	webhook `FUNDS_RECOVERY_EVENTS` de BTG	Evento de ciclo de vida de paso directo — sin actualización de base de datos

Ambos usan flowType: DICT. Consulta la guía de Webhooks para el formato del envoltorio, los reintentos y el enrutamiento. Evento de entidad de recuperación de fondos:

{
  "entityType": "FUNDS_RECOVERY",
  "flowType": "DICT",
  "payload": {
    "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
    "externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0",
    "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
    "status": "CREATED",
    "rootTransactionId": "E9999901012341234123412345678900",
    "situationType": "SCAM",
    "reporterParticipant": "99999010",
    "contactInformation": {},
    "reportDetails": "Details to help receiving participants",
    "createdAt": "2020-01-17T10:00:00.000Z",
    "updatedAt": "2020-01-17T10:00:00.000Z"
  }
}

Evento de ciclo de vida (paso directo):

{
  "entityType": "FUNDS_RECOVERY_EVENTS",
  "flowType": "DICT",
  "payload": {
    "id": "10001",
    "event": "FUNDS_RECOVERY_COMPLETED",
    "entityType": "FUNDS_RECOVERY",
    "entityId": "527179ce-b991-4add-a70f-e0fdbb98e6da",
    "timestamp": "2025-01-11T10:00:00.000Z"
  }
}

Valores de event del ciclo de vida: FUNDS_RECOVERY_ANALYSED, FUNDS_RECOVERY_COMPLETED, FUNDS_RECOVERY_INFORMATION_UPDATED, FUNDS_RECOVERY_CANCELLED.

Aviso de obsolescencia

No uses Crear un reporte de infracción para nuevas integraciones. MED 2.0 deja obsoleto este endpoint y crea reportes de infracción automáticamente a través del flujo de Recuperación de Fondos. El endpoint sigue funcionando por compatibilidad con versiones anteriores. Las nuevas integraciones deben usar las APIs de Recuperación de Fondos.

Próximos pasos

Operaciones de reembolso — Reembolsos parciales distribuidos y desbloqueo de reembolsos atascados
Webhooks — Envoltorio de eventos, reintentos y enrutamiento
Dominios principales: MED — Conceptos de disputa y reembolso de MED
Referencia de API — Documentación completa de la API

Resumen

Lerian SPI — mensajería nativa

JD — interfaz (Pix directo)

BTG — interfaz (Pix indirecto)

MED 2.0 — Recuperación de fondos

Conceptos

Ciclo de vida y estado

Endpoints

Crear una recuperación de fondos

Reglas de validación

Grafo de rastreo

Solicitar reembolsos

Encabezado X-Purpose (transferencias MED 2.0)

Campos de correlación

Webhooks

Aviso de obsolescencia

Próximos pasos

​Conceptos

​Ciclo de vida y estado

​Endpoints

​Crear una recuperación de fondos

​Reglas de validación

​Grafo de rastreo

​Solicitar reembolsos

​Encabezado X-Purpose (transferencias MED 2.0)

​Campos de correlación

​Webhooks

​Aviso de obsolescencia

​Próximos pasos

Conceptos

Ciclo de vida y estado

Endpoints

Crear una recuperación de fondos

Reglas de validación

Grafo de rastreo

Solicitar reembolsos

Encabezado X-Purpose (transferencias MED 2.0)

Campos de correlación

Webhooks

Aviso de obsolescencia

Próximos pasos