> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # MED 2.0 — Recuperação de Fundos > Opere o fluxo de Recuperação de Fundos do MED 2.0 do BACEN por meio do Plugin Pix Indireto (BTG): rastreie movimentações fraudulentas de fundos entre contas, analise relatos de infração e solicite devoluções. 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: Recuperação de Fundos | 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`](/pt/reference/midaz/plugins/indirect-pix/create-a-funds-recovery-request) | Criar uma recuperação de fundos | | `GET` | [`/v1/dict/funds-recoveries/{id}`](/pt/reference/midaz/plugins/indirect-pix/retrieve-funds-recovery-details) | Consultar uma recuperação de fundos | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/pt/reference/midaz/plugins/indirect-pix/update-a-funds-recovery-request) | Atualizar tipo de situação e informações de contato | | `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/pt/reference/midaz/plugins/indirect-pix/cancel-a-funds-recovery-request) | Cancelar (antes do início da devolução) | | `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/pt/reference/midaz/plugins/indirect-pix/retrieve-funds-recovery-tracking-graph) | Ver o grafo de rastreamento | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/pt/reference/midaz/plugins/indirect-pix/list-funds-recovery-infraction-reports) | Listar relatos de infração vinculados | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/pt/reference/midaz/plugins/indirect-pix/request-funds-recovery-refund) | Solicitar devoluções (status deve ser `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/pt/reference/midaz/plugins/indirect-pix/list-funds-recovery-refunds) | Listar solicitações de devolução | ## Criar uma recuperação de fundos *** ```json theme={null} 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](/pt/reference/midaz/plugins/indirect-pix/list-funds-recovery-refunds). # 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](/pt/reference/midaz/plugins/indirect-pix/retrieve-a-pix-transfer) 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](/pt/reference/midaz/plugins/indirect-pix/retrieve-an-infraction-report) e [o endpoint de listagem](/pt/reference/midaz/plugins/indirect-pix/list-infraction-reports) * **Solicitações de devolução** — [Recuperar uma solicitação de devolução](/pt/reference/midaz/plugins/indirect-pix/retrieve-a-refund-request) e [o endpoint de listagem](/pt/reference/midaz/plugins/indirect-pix/list-refund-requests) 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](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) para o formato do envelope, retentativas e roteamento. **Evento de entidade da recuperação de fundos:** ```json theme={null} { "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):** ```json theme={null} { "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](/pt/reference/midaz/plugins/indirect-pix/create-an-infraction-report) 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](/pt/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Devoluções parciais distribuídas e desbloqueio de devoluções presas * [Webhooks](/pt/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Envelope de eventos, retentativas e roteamento * [Domínios principais: MED](/pt/midaz/plugins/pix/main-domains-med) — Conceitos de disputa e devolução do MED * [Referência da API](/pt/reference/midaz/plugins/indirect-pix/create-entry) — Documentação completa da API