> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # MED 2.0 — Recuperación de fondos > Opera el flujo de Recuperación de Fondos de MED 2.0 de BACEN a través del Plugin Pix Indirecto (BTG): rastrea movimientos fraudulentos de fondos entre cuentas, analiza reportes de infracción y solicita reembolsos. 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: Recuperación de fondos | 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`](/es/reference/midaz/plugins/indirect-pix/create-a-funds-recovery-request) | Crear una recuperación de fondos | | `GET` | [`/v1/dict/funds-recoveries/{id}`](/es/reference/midaz/plugins/indirect-pix/retrieve-funds-recovery-details) | Consultar una recuperación de fondos | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/es/reference/midaz/plugins/indirect-pix/update-a-funds-recovery-request) | Actualizar el tipo de situación y la información de contacto | | `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/es/reference/midaz/plugins/indirect-pix/cancel-a-funds-recovery-request) | Cancelar (antes de que comiencen los reembolsos) | | `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/es/reference/midaz/plugins/indirect-pix/retrieve-funds-recovery-tracking-graph) | Ver el grafo de rastreo | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/es/reference/midaz/plugins/indirect-pix/list-funds-recovery-infraction-reports) | Listar los reportes de infracción vinculados | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/es/reference/midaz/plugins/indirect-pix/request-funds-recovery-refund) | Solicitar reembolsos (el estado debe ser `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/es/reference/midaz/plugins/indirect-pix/list-funds-recovery-refunds) | Listar las solicitudes de reembolso | ## Crear una recuperación de fondos *** ```json theme={null} 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](/es/reference/midaz/plugins/indirect-pix/list-funds-recovery-refunds). # 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](/es/reference/midaz/plugins/indirect-pix/retrieve-a-pix-transfer) 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](/es/reference/midaz/plugins/indirect-pix/retrieve-an-infraction-report) y [el endpoint de listado](/es/reference/midaz/plugins/indirect-pix/list-infraction-reports) * **Solicitudes de reembolso** — [Consultar una solicitud de reembolso](/es/reference/midaz/plugins/indirect-pix/retrieve-a-refund-request) y [el endpoint de listado](/es/reference/midaz/plugins/indirect-pix/list-refund-requests) 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](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks) para el formato del envoltorio, los reintentos y el enrutamiento. **Evento de entidad de recuperación de fondos:** ```json theme={null} { "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):** ```json theme={null} { "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](/es/reference/midaz/plugins/indirect-pix/create-an-infraction-report) 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](/es/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Reembolsos parciales distribuidos y desbloqueo de reembolsos atascados * [Webhooks](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Envoltorio de eventos, reintentos y enrutamiento * [Dominios principales: MED](/es/midaz/plugins/pix/main-domains-med) — Conceptos de disputa y reembolso de MED * [Referencia de API](/es/reference/midaz/plugins/indirect-pix/create-entry) — Documentación completa de la API