> ## 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 > Run BACEN's MED 2.0 Funds Recovery through the Pix Indirect Plugin via BTG: tracking graphs, infraction report analysis, refunds, and webhook events. MED 2.0 (Mecanismo Especial de Devolução) is BACEN's enhanced mechanism to recover funds in cases of fraud, scams, and operational errors. 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. The flow coordinates blocking, analysis, and refunds across the participating institutions. The Pix Indirect Plugin (BTG) exposes the full Funds Recovery lifecycle as REST endpoints. It also sends webhook events, so your system stays in sync with each status change. MED 2.0 is a BACEN requirement for Pix participants. The plugin implements the Funds Recovery flow, so you can meet this requirement through your BTG indirect connection. # 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/interfaces/pix-btg/create-a-funds-recovery-request) | Create a funds recovery | | `GET` | [`/v1/dict/funds-recoveries/{id}`](/en/reference/interfaces/pix-btg/retrieve-funds-recovery-details) | Consult a funds recovery | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/en/reference/interfaces/pix-btg/update-a-funds-recovery-request) | Update situation type and contact info | | `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/en/reference/interfaces/pix-btg/cancel-a-funds-recovery-request) | Cancel (before refund starts) | | `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/en/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph) | View the tracking graph | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/en/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports) | List linked infraction reports | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/en/reference/interfaces/pix-btg/request-funds-recovery-refund) | Request refunds (status must be `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/en/reference/interfaces/pix-btg/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**. The response contains the new funds recovery and its tracking graph data. The plugin persists the record locally with status `CREATED`. ## Tracking graph *** The plugin fetches the tracking graph fresh from BTG on every call. The graph has no local state. It lists the persons, accounts, and transactions in the fraud flow, with the refundable amount for each 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/interfaces/pix-btg/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). Transfer responses also include the `purpose` value ([Retrieve a Pix Transfer](/en/reference/interfaces/pix-btg/retrieve-a-pix-transfer) and the list endpoints). Existing records default to `TRANSFER`. # Correlation fields *** Two existing entities now carry a `fundsRecoveryId` field that links a dispute to its parent recovery: * **Infraction reports**: [Retrieve an Infraction Report](/en/reference/interfaces/pix-btg/retrieve-an-infraction-report) and [the list endpoint](/en/reference/interfaces/pix-btg/list-infraction-reports) * **Refund requests**: [Retrieve a Refund Request](/en/reference/interfaces/pix-btg/retrieve-a-refund-request) and [the list endpoint](/en/reference/interfaces/pix-btg/list-refund-requests) Records created outside the MED 2.0 flow do not carry this field. # Webhooks *** Two inbound BTG webhooks drive the Funds Recovery flow. Each one produces a matching outbound event to your system: | Outbound `entityType` | Trigger | Behavior | | ----------------------- | ----------------------------------- | ------------------------------------------------------------------------------- | | `FUNDS_RECOVERY` | BTG `FUNDS_RECOVERY` webhook | Plugin updates the local record, then notifies your system with the full entity | | `FUNDS_RECOVERY_EVENTS` | BTG `FUNDS_RECOVERY_EVENTS` webhook | Pass-through lifecycle event — no database update | Both use `flowType: DICT`. See the [Webhooks guide](/en/interfaces/pix-btg/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_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" } } ``` Lifecycle `event` values: `FUNDS_RECOVERY_ANALYSED`, `FUNDS_RECOVERY_COMPLETED`, `FUNDS_RECOVERY_INFORMATION_UPDATED`, `FUNDS_RECOVERY_CANCELLED`. # Deprecation notice *** Do not use [Create an Infraction Report](/en/reference/interfaces/pix-btg/create-an-infraction-report) for new integrations. MED 2.0 deprecates this endpoint and creates infraction reports automatically through the Funds Recovery flow. The endpoint still works for backward compatibility. New integrations must use the Funds Recovery APIs. # Next steps *** * [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations): Distributed partial refunds and unblocking stuck refunds * [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Event envelope, retries, and routing * [Main domains: MED](/en/interfaces/pix/main-domains-med): MED dispute and refund concepts * [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API documentation