O MED 2.0 (Mecanismo Especial de Devolução) é o mecanismo aprimorado do BACEN para recuperar fundos em casos de fraude, golpe e erro operacional. O MED 1.0 trata disputas de uma única transação por relatos de infração. O MED 2.0 introduz um fluxo de Recuperação de Fundos que rastreia como os fundos fraudulentos se moveram por várias 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 da Recuperação de Fundos como endpoints REST. Ele também envia eventos de webhook, então seu sistema fica em sincronia com cada mudança de status.

O MED 2.0 é uma exigência do BACEN para participantes do Pix. O plugin implementa o fluxo de Recuperação de Fundos, então você pode atender a essa exigência pela sua conexão indireta com o BTG.

Conceitos

Termo	Definição
Recuperação de Fundos	O processo do MED 2.0 que recupera fundos em várias contas depois de 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 começa a recuperação
Relato de Infração	Um relato de transação fraudulenta ou problemática, agora ligado à Recuperação de Fundos que o originou
Solicitação de Devolução	Uma solicitação para devolver à vítima os fundos bloqueados

Ciclo de vida e status

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

Status	Descrição
`CREATED`	Estado inicial depois da criação
`TRACKED`	Grafo de rastreamento gerado
`AWAITING_ANALYSIS`	Fluxo de bloqueio iniciado, aguardando a análise dos relatos de infração
`ANALYSED`	Todos os relatos de infração analisados, pronto para a devolução
`REFUNDING`	Solicitações de devolução iniciadas
`COMPLETED`	Todas as devoluções concluídas
`CANCELLED`	Recuperação cancelada (permitida apenas antes de a devolução começar)

Endpoints

Todos os endpoints de Recuperação de Fundos ficam no domínio DICT e exigem o header 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 o tipo de situação e os dados de contato
`POST`	`/v1/dict/funds-recoveries/{id}/cancel`	Cancelar (antes de a devolução começar)
`GET`	`/v1/dict/funds-recoveries/{id}/tracking-graph`	Ver o grafo de rastreamento
`GET`	`/v1/dict/funds-recoveries/{id}/infraction-reports`	Listar os relatos de infração ligados
`POST`	`/v1/dict/funds-recoveries/{id}/refund`	Solicitar devoluções (o status deve ser `ANALYSED`)
`GET`	`/v1/dict/funds-recoveries/{id}/refunds`	Listar as 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 entre `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 (por exemplo, `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 no BTG a cada chamada. O grafo não tem estado local. Ele lista as pessoas, contas e transações do fluxo de fraude, com o valor devolvível 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 do fluxo, com o ISPB do participante de cada uma
transactions[]: transações Pix com valores e valores devolvíveis

Solicitar devoluções

Quando a recuperação chega a ANALYSED, solicite a devolução dos fundos bloqueados:

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

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

Header 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 cash-out aceita um header X-Purpose opcional 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 comum (padrão quando o header é omitido)	`TRANSFER`
`INSTANT_PAYMENT_REFUND`	Transferência de devolução do MED 2.0	`INSTANT_PAYMENT_REFUND`

Apenas TRANSFER e INSTANT_PAYMENT_REFUND são aceitos atualmente. 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 trazem o valor de purpose (Consultar uma transferência Pix e os endpoints de listagem). Os registros existentes assumem TRANSFER como padrão.

Campos de correlação

Duas entidades existentes agora carregam um campo fundsRecoveryId que liga uma disputa à recuperação que a originou:

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

Os registros criados fora do fluxo MED 2.0 não carregam 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 avisa seu sistema com a entidade completa
`FUNDS_RECOVERY_EVENTS`	Webhook `FUNDS_RECOVERY_EVENTS` do BTG	Evento de ciclo de vida repassado — sem atualização no banco

Os dois usam flowType: DICT. Veja o guia de Webhooks para formato do envelope, novas tentativas e roteamento. Evento de entidade de 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 (repasse):

{
  "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 do 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 em novas integrações. O MED 2.0 descontinua esse endpoint e cria os relatos de infração automaticamente pelo fluxo de Recuperação de Fundos. O endpoint continua funcionando por compatibilidade retroativa. As 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 travadas
Webhooks: Envelope de evento, novas tentativas 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

​Header 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

Header X-Purpose (transferências MED 2.0)

Campos de correlação

Webhooks

Aviso de descontinuação

Próximos passos