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. Mientras que 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 y 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, además de eventos de webhook para que tu sistema se mantenga sincronizado con cada cambio de estado.

MED 2.0 es un requisito regulatorio de BACEN. No hay una ruta alternativa — los clientes deben operar la Recuperación de Fondos a través del plugin para mantenerse en cumplimiento.

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 con la recuperación de fondos creada y sus datos del grafo de rastreo, persistidos localmente con estado CREATED.

Grafo de rastreo

El grafo de rastreo se obtiene fresco de BTG en cada llamada (sin estado). Devuelve las personas, cuentas y transacciones involucradas en el flujo del fraude, incluyendo los montos reembolsables por 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).

El valor purpose también se devuelve en las respuestas de transferencia (Consultar una transferencia Pix y los endpoints de listado), con TRANSFER por defecto para los registros existentes.

Campos de correlación

Para correlacionar las disputas con su recuperación principal, dos entidades existentes ahora exponen un fundRecoveryId nullable:

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

El campo es null para los registros creados fuera del flujo de MED 2.0.

Webhooks

Dos webhooks entrantes desde BTG impulsan el flujo de Recuperación de Fondos, cada uno produciendo un evento saliente correspondiente hacia tu sistema:

`entityType` saliente	Disparador	Comportamiento
`FUNDS_RECOVERY`	`DictHubFundsRecovery` de BTG	El plugin actualiza el registro local, luego notifica a tu sistema con la entidad completa
`FUNDS_RECOVERY_EVENT`	`DictHubFundsRecoveryEvents` 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_EVENT",
  "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

Con la adopción de MED 2.0, Crear un reporte de infracción está obsoleto. MED 2.0 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, pero las nuevas integraciones deben usar las APIs de Recuperación de Fondos. Las llamadas al endpoint obsoleto se registran con una advertencia de obsolescencia.

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

​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