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:

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`	Create a funds recovery
`GET`	`/v1/dict/funds-recoveries/{id}`	Consult a funds recovery
`PATCH`	`/v1/dict/funds-recoveries/{id}`	Update situation type and contact info
`POST`	`/v1/dict/funds-recoveries/{id}/cancel`	Cancel (before refund starts)
`GET`	`/v1/dict/funds-recoveries/{id}/tracking-graph`	View the tracking graph
`GET`	`/v1/dict/funds-recoveries/{id}/infraction-reports`	List linked infraction reports
`POST`	`/v1/dict/funds-recoveries/{id}/refund`	Request refunds (status must be `ANALYSED`)
`GET`	`/v1/dict/funds-recoveries/{id}/refunds`	List refund requests

Create a funds recovery

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.

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 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 and the list endpoint
Refund requests — Retrieve a Refund Request and the list endpoint

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 for envelope format, retries, and routing. Funds recovery entity event:

{
  "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):

{
  "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 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 — Distributed partial refunds and unblocking stuck refunds
Webhooks — Event envelope, retries, and routing
Main domains: MED — MED dispute and refund concepts
API reference — Full API documentation

​Concepts

​Lifecycle and status

​Endpoints

​Create a funds recovery

​Validation rules

​Tracking graph

​Request refunds

​X-Purpose header (MED 2.0 transfers)

​Correlation fields

​Webhooks

​Deprecation notice

​Next steps

Concepts

Lifecycle and status

Endpoints

Create a funds recovery

Validation rules

Tracking graph

Request refunds

X-Purpose header (MED 2.0 transfers)

Correlation fields

Webhooks

Deprecation notice

Next steps