> ## 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 > Execute a Recuperação de Fundos do MED 2.0 do BACEN pelo Plugin Pix Indireto via BTG: grafos de rastreamento, análise de relatos de infração, devoluções e eventos de webhook. 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: Recuperação de Fundos | 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`](/pt/reference/interfaces/pix-btg/create-a-funds-recovery-request) | Criar uma recuperação de fundos | | `GET` | [`/v1/dict/funds-recoveries/{id}`](/pt/reference/interfaces/pix-btg/retrieve-funds-recovery-details) | Consultar uma recuperação de fundos | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/pt/reference/interfaces/pix-btg/update-a-funds-recovery-request) | Atualizar o tipo de situação e os dados de contato | | `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/pt/reference/interfaces/pix-btg/cancel-a-funds-recovery-request) | Cancelar (antes de a devolução começar) | | `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/pt/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph) | Ver o grafo de rastreamento | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/pt/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports) | Listar os relatos de infração ligados | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/pt/reference/interfaces/pix-btg/request-funds-recovery-refund) | Solicitar devoluções (o status deve ser `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/pt/reference/interfaces/pix-btg/list-funds-recovery-refunds) | Listar as 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 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](/pt/reference/interfaces/pix-btg/list-funds-recovery-refunds). # 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](/pt/reference/interfaces/pix-btg/retrieve-a-pix-transfer) 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](/pt/reference/interfaces/pix-btg/retrieve-an-infraction-report) e [o endpoint de listagem](/pt/reference/interfaces/pix-btg/list-infraction-reports) * **Solicitações de devolução**: [Consultar uma solicitação de devolução](/pt/reference/interfaces/pix-btg/retrieve-a-refund-request) e [o endpoint de listagem](/pt/reference/interfaces/pix-btg/list-refund-requests) 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](/pt/interfaces/pix-btg/indirect-pix-webhooks) para formato do envelope, novas tentativas e roteamento. **Evento de entidade de 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 (repasse):** ```json theme={null} { "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](/pt/reference/interfaces/pix-btg/create-an-infraction-report) 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](/pt/interfaces/pix-btg/indirect-pix-refund-operations): Devoluções parciais distribuídas e desbloqueio de devoluções travadas * [Webhooks](/pt/interfaces/pix-btg/indirect-pix-webhooks): Envelope de evento, novas tentativas e roteamento * [Domínios principais: MED](/pt/interfaces/pix/main-domains-med): Conceitos de disputa e devolução do MED * [Referência da API](/pt/reference/interfaces/pix-btg/create-entry): Documentação completa da API