O MED 2.0 (Mecanismo Especial de Devolução) é o mecanismo aprimorado do BACEN para recuperar fundos em casos de fraude, golpes e erros operacionais. Enquanto o MED 1.0 trata disputas de transação única por meio de relatos de infração, o MED 2.0 introduz um fluxo de Recuperação de Fundos que rastreia como os fundos fraudulentos se moveram entre múltiplas contas e coordena bloqueio, análise e devoluções entre as instituições participantes. O Plugin Pix Indireto (BTG) expõe todo o ciclo de vida de Recuperação de Fundos como endpoints REST, além de eventos de webhook para que seu sistema permaneça sincronizado com cada mudança de status.

O MED 2.0 é um requisito regulatório do BACEN. Não há caminho alternativo — os clientes devem operar a Recuperação de Fundos por meio do plugin para permanecerem em conformidade.

Conceitos

Termo	Definição
Recuperação de Fundos	O processo do MED 2.0 que recupera fundos entre múltiplas contas após uma fraude relatada
Grafo de rastreamento	Uma representação de como os fundos fluíram entre contas, pessoas e transações
Transação raiz	A transação Pix fraudulenta original que inicia a recuperação
Relato de infração	Um relato de uma transação fraudulenta/problemática, agora vinculada à sua Recuperação de Fundos pai
Solicitação de devolução	Uma solicitação para devolver os fundos bloqueados à vítima

Ciclo de vida e status

Uma Recuperação de Fundos passa pelos seguintes estados:

Status	Descrição
`CREATED`	Estado inicial após a criação
`TRACKED`	Grafo de rastreamento gerado
`AWAITING_ANALYSIS`	Fluxo de bloqueio iniciado, aguardando análise do relato de infração
`ANALYSED`	Todos os relatos de infração analisados, prontos para devolução
`REFUNDING`	Solicitações de devolução iniciadas
`COMPLETED`	Todas as devoluções concluídas
`CANCELLED`	Recuperação cancelada (permitido apenas antes do início da devolução)

Endpoints

Todos os endpoints de Recuperação de Fundos ficam no domínio DICT e exigem o cabeçalho X-Account-Id.

Método	Endpoint	Descrição
`POST`	`/v1/dict/funds-recoveries`	Criar uma recuperação de fundos
`GET`	`/v1/dict/funds-recoveries/{id}`	Consultar uma recuperação de fundos
`PATCH`	`/v1/dict/funds-recoveries/{id}`	Atualizar tipo de situação e informações de contato
`POST`	`/v1/dict/funds-recoveries/{id}/cancel`	Cancelar (antes do início da devolução)
`GET`	`/v1/dict/funds-recoveries/{id}/tracking-graph`	Ver o grafo de rastreamento
`GET`	`/v1/dict/funds-recoveries/{id}/infraction-reports`	Listar relatos de infração vinculados
`POST`	`/v1/dict/funds-recoveries/{id}/refund`	Solicitar devoluções (status deve ser `ANALYSED`)
`GET`	`/v1/dict/funds-recoveries/{id}/refunds`	Listar solicitações de devolução

Criar uma recuperação de fundos

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

Regras de validação

Campo	Requisito
`rootTransactionId`	Obrigatório, 32 caracteres alfanuméricos
`situationType`	Obrigatório — um dentre `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`, `UNKNOWN`
`contactInformation`	Obrigatório — objeto com `email` e/ou `phone`
`trackingGraphParameters.minTransactionAmount`	Opcional, decimal positivo
`trackingGraphParameters.maxTransactions`	Opcional, 1–1000
`trackingGraphParameters.hopWindow`	Opcional, duração ISO 8601 (ex.: `PT24H`)
`trackingGraphParameters.maxHops`	Opcional, 1–10

Uma chamada bem-sucedida retorna HTTP 201 com a recuperação de fundos criada e os dados do seu grafo de rastreamento, persistidos localmente com status CREATED.

Grafo de rastreamento

O grafo de rastreamento é buscado do BTG a cada chamada (stateless). Ele retorna as pessoas, contas e transações envolvidas no fluxo da fraude, incluindo os valores passíveis de devolução por transação.

GET /v1/dict/funds-recoveries/{id}/tracking-graph

A resposta inclui:

parameters — os parâmetros de geração do grafo
persons[] — pessoas físicas e jurídicas envolvidas
accounts[] — contas no fluxo com os ISPBs de seus participantes
transactions[] — transações Pix com valores e valores passíveis de devolução

Solicitar devoluções

Assim que a recuperação atinge ANALYSED, solicite a devolução dos fundos bloqueados:

POST /v1/dict/funds-recoveries/{id}/refund

O plugin chama o BTG, transiciona a recuperação para REFUNDING e retorna HTTP 200. Acompanhe os status de devolução individuais com Listar devoluções.

Cabeçalho X-Purpose (transferências MED 2.0)

As transferências de devolução do MED 2.0 devem carregar uma finalidade de transação. O endpoint de cashout aceita um cabeçalho opcional X-Purpose que o plugin mapeia para o transactionType do BTG.

POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND

Valor	Descrição	`transactionType` do BTG
`TRANSFER`	Transferência Pix padrão (default quando o cabeçalho é omitido)	`TRANSFER`
`INSTANT_PAYMENT_REFUND`	Transferência de devolução do MED 2.0	`INSTANT_PAYMENT_REFUND`

Atualmente, apenas TRANSFER e INSTANT_PAYMENT_REFUND têm suporte. Os valores CHANGE, WITHDRAWAL, REFUND_AUTOMATIC_PIX e INSTALLMENT_PIX retornam HTTP 400 com o erro PIX-0429 (Unsupported Purpose).

O valor purpose também é retornado nas respostas de transferência (Recuperar uma transferência Pix e endpoints de listagem), com default TRANSFER para registros existentes.

Campos de correlação

Para correlacionar disputas com sua recuperação pai, duas entidades existentes agora expõem um fundRecoveryId anulável:

Relatos de infração — Recuperar um relato de infração e o endpoint de listagem
Solicitações de devolução — Recuperar uma solicitação de devolução e o endpoint de listagem

O campo é null para registros criados fora do fluxo do MED 2.0.

Webhooks

Dois webhooks de entrada do BTG conduzem o fluxo de Recuperação de Fundos, cada um produzindo um evento de saída correspondente para o seu sistema:

`entityType` de saída	Gatilho	Comportamento
`FUNDS_RECOVERY`	`DictHubFundsRecovery` do BTG	O plugin atualiza o registro local e depois notifica seu sistema com a entidade completa
`FUNDS_RECOVERY_EVENT`	`DictHubFundsRecoveryEvents` do BTG	Evento de ciclo de vida pass-through — sem atualização no banco de dados

Ambos usam flowType: DICT. Consulte o guia de Webhooks para o formato do envelope, retentativas e roteamento. Evento de entidade da recuperação de fundos:

{
  "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 (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"
  }
}

Valores de event de ciclo de vida: FUNDS_RECOVERY_ANALYSED, FUNDS_RECOVERY_COMPLETED, FUNDS_RECOVERY_INFORMATION_UPDATED, FUNDS_RECOVERY_CANCELLED.

Aviso de descontinuação

Com a adoção do MED 2.0, Criar um relato de infração está descontinuado. O MED 2.0 cria relatos de infração automaticamente por meio do fluxo de Recuperação de Fundos. O endpoint ainda funciona para compatibilidade retroativa, mas novas integrações devem usar as APIs de Recuperação de Fundos. Chamadas ao endpoint descontinuado são registradas em log com um aviso de descontinuação.

Próximos passos

Operações de devolução — Devoluções parciais distribuídas e desbloqueio de devoluções presas
Webhooks — Envelope de eventos, retentativas e roteamento
Domínios principais: MED — Conceitos de disputa e devolução do MED
Referência da API — Documentação completa da API

​Conceitos

​Ciclo de vida e status

​Endpoints

​Criar uma recuperação de fundos

​Regras de validação

​Grafo de rastreamento

​Solicitar devoluções

​Cabeçalho X-Purpose (transferências MED 2.0)

​Campos de correlação

​Webhooks

​Aviso de descontinuação

​Próximos passos

Conceitos

Ciclo de vida e status

Endpoints

Criar uma recuperação de fundos

Regras de validação

Grafo de rastreamento

Solicitar devoluções

Cabeçalho X-Purpose (transferências MED 2.0)

Campos de correlação

Webhooks

Aviso de descontinuação

Próximos passos