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. 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. O fluxo 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. Ele também envia eventos de webhook, para que seu sistema permaneça sincronizado com cada mudança de status.

O MED 2.0 é um requisito do BACEN para os participantes do Pix. O plugin implementa o fluxo de Recuperação de Fundos, para que você possa cumprir esse requisito por meio da sua conexão indireta com o BTG.

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. A resposta contém a nova recuperação de fundos e os dados do seu grafo de rastreamento. O plugin persiste o registro localmente com status CREATED.

Grafo de rastreamento

O plugin busca o grafo de rastreamento do BTG a cada chamada. O grafo não tem estado local. Ele lista as pessoas, contas e transações do fluxo da fraude, com o valor passível de devolução de cada 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).

As respostas de transferência também incluem o valor purpose (Recuperar uma transferência Pix e os endpoints de listagem). Os registros existentes usam TRANSFER como padrão.

Campos de correlação

Duas entidades existentes agora incluem um campo fundsRecoveryId que vincula uma disputa à sua recuperação pai:

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

Os registros criados fora do fluxo do MED 2.0 não incluem esse campo.

Webhooks

Dois webhooks de entrada do BTG conduzem o fluxo de Recuperação de Fundos. Cada um produz um evento de saída correspondente para o seu sistema:

`entityType` de saída	Gatilho	Comportamento
`FUNDS_RECOVERY`	webhook `FUNDS_RECOVERY` do BTG	O plugin atualiza o registro local e depois notifica seu sistema com a entidade completa
`FUNDS_RECOVERY_EVENTS`	webhook `FUNDS_RECOVERY_EVENTS` 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_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"
  }
}

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

Aviso de descontinuação

Não use Criar um relato de infração para novas integrações. O MED 2.0 descontinua este endpoint e cria relatos de infração automaticamente por meio do fluxo de Recuperação de Fundos. O endpoint ainda funciona para compatibilidade retroativa. Novas integrações devem usar as APIs de Recuperação de Fundos.

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

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

MED 2.0 — Recuperação de Fundos

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

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