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

Método	Endpoint	Descrição
`GET`	`/v1/dict/funds-recoveries`	Listar as recuperações de fundos
`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": 5,
    "hopWindow": "PT24H",
    "maxHops": 2
  }
}

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 `phone` (`+`, código do país e número)
`reportDetails`	Opcional, até 2000 caracteres
`trackingGraphParameters.minTransactionAmount`	Opcional, de 1 a 10 dígitos, um ponto e 2 casas decimais (por exemplo, `10.00`)
`trackingGraphParameters.maxTransactions`	Opcional, pelo menos 1
`trackingGraphParameters.hopWindow`	Opcional, duração ISO 8601 (por exemplo, `PT24H`)
`trackingGraphParameters.maxHops`	Opcional, de 1 a 2

O plugin trata um maxTransactions ou maxHops igual a 0 como não enviado. Ele recusa qualquer outro valor de minTransactionAmount, maxTransactions ou maxHops fora dessas regras com PIX-0004. O BTG define o limite superior de maxTransactions. Quando o BTG recusa um parâmetro do grafo de rastreamento, o plugin retorna PIX-0295, e o objeto fields pode trazer a faixa que o BTG aceita. 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, valores devolvíveis e transactionDepth, a profundidade da transação no grafo (a transação raiz é 1)

O BTG monta o grafo com os trackingGraphParameters da chamada de criação. Os parâmetros de consulta min_transaction_amount, max_transactions, hop_window e max_hops estão obsoletos, e o grafo não os usa.

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 envia ao BTG como transactionType.

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`
`WITHDRAWAL`	Pix Saque: paga uma cobrança que traz um saque	`WITHDRAWAL`
`CHANGE`	Pix Troco: paga uma cobrança que traz uma compra e um saque	`CHANGE`

WITHDRAWAL e CHANGE devem corresponder à cobrança que a transferência paga. Se não corresponderem, o plugin retorna HTTP 400 com o erro PIX-0496. Os valores 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 carregam um campo bacenFundsRecoveryId 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. Os relatos de infração também carregam transactionDepth: a profundidade da transação do relato no grafo de rastreamento do DICT, em que a transação raiz é 1. O DICT define esse valor. Quando o DICT não o envia, o campo fica ausente.

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 os campos principais
`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",
    "rootTransactionId": "E9999901012341234123412345678900",
    "situationType": "SCAM",
    "status": "CREATED",
    "reporterParticipant": "99999010",
    "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": {
    "pactualId": "74ab3e2c-f69c-4a59-a507-8302186ee743",
    "clientRequestId": "40a9bab9eda647f1b21c17bba36e2add",
    "entity": "FundsRecoveryEvents",
    "status": "FUNDS_RECOVERY_COMPLETED",
    "createTimestamp": "2025-01-11T10:00:00Z",
    "body": {
      "id": "10001",
      "event": "FUNDS_RECOVERY_COMPLETED",
      "entityType": "FUNDS_RECOVERY",
      "entityId": "527179ce-b991-4add-a70f-e0fdbb98e6da",
      "timestamp": "2025-01-11T10:00:00.000Z"
    }
  }
}

Valores de body.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 nem Encerrar um relato de infração em novas integrações. O MED 2.0 descontinua os dois endpoints e gerencia os relatos de infração pelo fluxo de Recuperação de Fundos. Os endpoints continuam 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

Introdução

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

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

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

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