> ## 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 — Funds Recovery > Operate BACEN's MED 2.0 Funds Recovery flow through the Pix Indirect Plugin (BTG): track fraudulent fund movements across accounts, analyze infraction reports, and request refunds. MED 2.0 (Mecanismo Especial de Devolução) is BACEN's enhanced mechanism for recovering funds in cases of fraud, scams, and operational errors. While MED 1.0 handles single-transaction disputes through infraction reports, **MED 2.0 introduces a Funds Recovery flow** that tracks how fraudulent funds moved across multiple accounts and coordinates blocking, analysis, and refunds across participating institutions. The Pix Indirect Plugin (BTG) exposes the full Funds Recovery lifecycle as REST endpoints, plus webhook events so your system stays in sync with each status change. MED 2.0 is a BACEN regulatory requirement. There is no alternative path — clients must operate Funds Recovery through the plugin to remain compliant. # Concepts *** | Term | Definition | | --------------------- | ----------------------------------------------------------------------------------------- | | **Funds Recovery** | The MED 2.0 process that recovers funds across multiple accounts after a reported fraud | | **Tracking Graph** | A representation of how funds flowed across accounts, persons, and transactions | | **Root transaction** | The original fraudulent Pix transaction that starts the recovery | | **Infraction Report** | A report of a fraudulent/problematic transaction, now linked to its parent Funds Recovery | | **Refund Request** | A request to return blocked funds to the victim | # Lifecycle and status *** A Funds Recovery moves through the following states: Funds Recovery | Status | Description | | ------------------- | ---------------------------------------------------------- | | `CREATED` | Initial state after creation | | `TRACKED` | Tracking graph generated | | `AWAITING_ANALYSIS` | Blocking flow started, awaiting infraction report analysis | | `ANALYSED` | All infraction reports analysed, ready for refund | | `REFUNDING` | Refund requests initiated | | `COMPLETED` | All refunds completed | | `CANCELLED` | Recovery cancelled (only allowed before refund starts) | # Endpoints *** All Funds Recovery endpoints live under the DICT domain and require the `X-Account-Id` header. | Method | Endpoint | Description | | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `POST` | [`/v1/dict/funds-recoveries`](/en/reference/midaz/plugins/indirect-pix/create-a-funds-recovery-request) | Create a funds recovery | | `GET` | [`/v1/dict/funds-recoveries/{id}`](/en/reference/midaz/plugins/indirect-pix/retrieve-funds-recovery-details) | Consult a funds recovery | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/en/reference/midaz/plugins/indirect-pix/update-a-funds-recovery-request) | Update situation type and contact info | | `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/en/reference/midaz/plugins/indirect-pix/cancel-a-funds-recovery-request) | Cancel (before refund starts) | | `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/en/reference/midaz/plugins/indirect-pix/retrieve-funds-recovery-tracking-graph) | View the tracking graph | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/en/reference/midaz/plugins/indirect-pix/list-funds-recovery-infraction-reports) | List linked infraction reports | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/en/reference/midaz/plugins/indirect-pix/request-funds-recovery-refund) | Request refunds (status must be `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/en/reference/midaz/plugins/indirect-pix/list-funds-recovery-refunds) | List refund requests | ## Create a funds recovery *** ```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 } } ``` ### Validation rules | Field | Requirement | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `rootTransactionId` | Required, 32 alphanumeric characters | | `situationType` | Required — one of `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`, `UNKNOWN` | | `contactInformation` | Required — object with `email` and/or `phone` | | `trackingGraphParameters.minTransactionAmount` | Optional, positive decimal | | `trackingGraphParameters.maxTransactions` | Optional, 1–1000 | | `trackingGraphParameters.hopWindow` | Optional, ISO 8601 duration (e.g. `PT24H`) | | `trackingGraphParameters.maxHops` | Optional, 1–10 | A successful call returns **HTTP 201** with the created funds recovery and its tracking graph data, persisted locally with status `CREATED`. ## Tracking graph *** The tracking graph is fetched fresh from BTG on every call (stateless). It returns the persons, accounts, and transactions involved in the fraud flow, including refundable amounts per transaction. ``` GET /v1/dict/funds-recoveries/{id}/tracking-graph ``` Response includes: * `parameters` — the graph generation parameters * `persons[]` — natural and legal persons involved * `accounts[]` — accounts in the flow with their participant ISPBs * `transactions[]` — Pix transactions with amounts and refundable amounts ## Request refunds *** Once the recovery reaches `ANALYSED`, request the return of blocked funds: ``` POST /v1/dict/funds-recoveries/{id}/refund ``` The plugin calls BTG, transitions the recovery to `REFUNDING`, and returns **HTTP 200**. Track individual refund statuses with [List Refunds](/en/reference/midaz/plugins/indirect-pix/list-funds-recovery-refunds). # X-Purpose header (MED 2.0 transfers) *** MED 2.0 refund transfers must carry a transaction purpose. The cashout endpoint accepts an optional `X-Purpose` header that the plugin maps to BTG's `transactionType`. ``` POST /v1/transfers/cashout/process X-Purpose: INSTANT_PAYMENT_REFUND ``` | Value | Description | BTG `transactionType` | | ------------------------ | ------------------------------------------------------ | ------------------------ | | `TRANSFER` | Standard Pix transfer (default when header is omitted) | `TRANSFER` | | `INSTANT_PAYMENT_REFUND` | MED 2.0 refund transfer | `INSTANT_PAYMENT_REFUND` | Only `TRANSFER` and `INSTANT_PAYMENT_REFUND` are currently supported. The values `CHANGE`, `WITHDRAWAL`, `REFUND_AUTOMATIC_PIX`, and `INSTALLMENT_PIX` return **HTTP 400** with error `PIX-0429` (Unsupported Purpose). The `purpose` value is also returned on transfer responses ([Retrieve a Pix Transfer](/en/reference/midaz/plugins/indirect-pix/retrieve-a-pix-transfer) and list endpoints), defaulting to `TRANSFER` for existing records. # Correlation fields *** To correlate disputes with their parent recovery, two existing entities now expose a nullable `fundRecoveryId`: * **Infraction reports** — [Retrieve an Infraction Report](/en/reference/midaz/plugins/indirect-pix/retrieve-an-infraction-report) and [the list endpoint](/en/reference/midaz/plugins/indirect-pix/list-infraction-reports) * **Refund requests** — [Retrieve a Refund Request](/en/reference/midaz/plugins/indirect-pix/retrieve-a-refund-request) and [the list endpoint](/en/reference/midaz/plugins/indirect-pix/list-refund-requests) The field is `null` for records created outside the MED 2.0 flow. # Webhooks *** Two inbound webhooks from BTG drive the Funds Recovery flow, each producing a matching outbound event to your system: | Outbound `entityType` | Trigger | Behavior | | ---------------------- | -------------------------------- | ------------------------------------------------------------------------------- | | `FUNDS_RECOVERY` | BTG `DictHubFundsRecovery` | Plugin updates the local record, then notifies your system with the full entity | | `FUNDS_RECOVERY_EVENT` | BTG `DictHubFundsRecoveryEvents` | Pass-through lifecycle event — no database update | Both use `flowType: DICT`. See the [Webhooks guide](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks) for envelope format, retries, and routing. **Funds recovery entity event:** ```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" } } ``` **Lifecycle event (pass-through):** ```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" } } ``` Lifecycle `event` values: `FUNDS_RECOVERY_ANALYSED`, `FUNDS_RECOVERY_COMPLETED`, `FUNDS_RECOVERY_INFORMATION_UPDATED`, `FUNDS_RECOVERY_CANCELLED`. # Deprecation notice *** With MED 2.0 adoption, [Create an Infraction Report](/en/reference/midaz/plugins/indirect-pix/create-an-infraction-report) is **deprecated**. MED 2.0 creates infraction reports automatically through the Funds Recovery flow. The endpoint still works for backward compatibility, but new integrations should use the Funds Recovery APIs. Calls to the deprecated endpoint are logged with a deprecation warning. # Next steps *** * [Refund operations](/en/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Distributed partial refunds and unblocking stuck refunds * [Webhooks](/en/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Event envelope, retries, and routing * [Main domains: MED](/en/midaz/plugins/pix/main-domains-med) — MED dispute and refund concepts * [API reference](/en/reference/midaz/plugins/indirect-pix/create-entry) — Full API documentation