MED 2.0 (Mecanismo Especial de Devolução) 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 mediante informes de infracción. MED 2.0 introduce un flujo de recuperación de fondos que rastrea cómo se movieron los fondos fraudulentos entre varias cuentas. El flujo coordina el bloqueo, el análisis y las devoluciones entre las instituciones participantes. El Plugin Pix Indirecto (BTG) expone el ciclo de vida completo de la recuperación de fondos como endpoints REST. También envía eventos por 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 varias cuentas después de un fraude denunciado
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
Informe de infracción	Un informe de una transacción fraudulenta/problemática, ahora vinculado a su recuperación de fondos padre
Solicitud de devolución	Una solicitud para devolver los fondos bloqueados a la víctima

Ciclo de vida y estado

Una recuperación de fondos pasa por los siguientes estados:

Estado	Descripción
`CREATED`	Estado inicial después de la creación
`TRACKED`	Grafo de rastreo generado
`AWAITING_ANALYSIS`	Flujo de bloqueo iniciado, a la espera del análisis de los informes de infracción
`ANALYSED`	Todos los informes de infracción analizados, listo para la devolución
`REFUNDING`	Solicitudes de devolución iniciadas
`COMPLETED`	Todas las devoluciones completadas
`CANCELLED`	Recuperación cancelada (solo se permite antes de que empiece la devolución)

Endpoints

Todos los endpoints de recuperación de fondos viven bajo el dominio DICT y requieren el header 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 los datos de contacto
`POST`	`/v1/dict/funds-recoveries/{id}/cancel`	Cancelar (antes de que empiece la devolución)
`GET`	`/v1/dict/funds-recoveries/{id}/tracking-graph`	Ver el grafo de rastreo
`GET`	`/v1/dict/funds-recoveries/{id}/infraction-reports`	Listar los informes de infracción vinculados
`POST`	`/v1/dict/funds-recoveries/{id}/refund`	Solicitar devoluciones (el estado debe ser `ANALYSED`)
`GET`	`/v1/dict/funds-recoveries/{id}/refunds`	Listar las solicitudes de devolución

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`	Obligatorio, 32 caracteres alfanuméricos
`situationType`	Obligatorio — uno de `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`, `UNKNOWN`
`contactInformation`	Obligatorio — objeto con `email` o `phone`, o ambos
`trackingGraphParameters.minTransactionAmount`	Opcional, decimal positivo
`trackingGraphParameters.maxTransactions`	Opcional, 1–1000
`trackingGraphParameters.hopWindow`	Opcional, duración ISO 8601 (por ejemplo, `PT24H`)
`trackingGraphParameters.maxHops`	Opcional, 1–10

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

Grafo de rastreo

El plugin obtiene el grafo de rastreo actualizado desde BTG en cada llamada. El grafo no tiene estado local. Lista las personas, las cuentas y las transacciones del flujo de 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[]: las personas físicas y jurídicas involucradas
accounts[]: las cuentas del flujo con los ISPB de sus participantes
transactions[]: las transacciones Pix con sus montos y montos reembolsables

Solicitar devoluciones

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

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

El plugin llama a BTG, hace la transición de la recuperación a REFUNDING y devuelve HTTP 200. Sigue el estado de cada devolución con Listar devoluciones.

Header X-Purpose (transferencias MED 2.0)

Las transferencias de devolución de MED 2.0 deben llevar un propósito de transacción. El endpoint de cashout acepta un header X-Purpose opcional 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 (predeterminado cuando se omite el header)	`TRANSFER`
`INSTANT_PAYMENT_REFUND`	Transferencia de devolución 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 tienen TRANSFER como valor predeterminado.

Campos de correlación

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

Informes de infracción: Consultar un informe de infracción y el endpoint de listado
Solicitudes de devolución: Consultar una solicitud de devolución y el endpoint de listado

Los registros creados fuera del flujo de MED 2.0 no llevan 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 y 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 — sin actualización en la base de datos

Ambos usan flowType: DICT. Consulta la guía de Webhooks para el formato del envelope, 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 (de paso):

{
  "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 deprecación

No uses Crear un informe de infracción para integraciones nuevas. MED 2.0 deprecia este endpoint y crea los informes de infracción automáticamente mediante el flujo de recuperación de fondos. El endpoint sigue funcionando por compatibilidad con versiones anteriores. Las integraciones nuevas deben usar las APIs de recuperación de fondos.

Próximos pasos

Operaciones de devolución: Devoluciones parciales distribuidas y desbloqueo de devoluciones atascadas
Webhooks: Envelope del evento, reintentos y enrutamiento
Dominios principales: MED: Conceptos de disputas y devoluciones 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 devoluciones

​Header X-Purpose (transferencias MED 2.0)

​Campos de correlación

​Webhooks

​Aviso de deprecación

​Próximos pasos

Conceptos

Ciclo de vida y estado

Endpoints

Crear una recuperación de fondos

Reglas de validación

Grafo de rastreo

Solicitar devoluciones

Header X-Purpose (transferencias MED 2.0)

Campos de correlación

Webhooks

Aviso de deprecación

Próximos pasos