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:

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. 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.

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

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 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_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 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 — 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

Overview

Lerian SPI — native messaging

JD — interface (direct Pix)

BTG — interface (indirect Pix)

MED 2.0 — Funds Recovery

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

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