> ## 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. > [!NOTE] > > 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: ![Recuperação de Fundos](https://mintcdn.com/lerian-49cb71fc/vdBt8wfgjsNRO1rf/images/pt/d2/indirect-pix-funds-recovery.svg?fit=max\&auto=format\&n=vdBt8wfgjsNRO1rf\&q=85\&s=a0682fc46cdbbe29a1249fba18387989) | 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`](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-funds-recoveries) | Listar as recuperações de fundos, opcionalmente filtradas por `bacen_funds_recovery_id` | | `POST` | [`/v1/dict/funds-recoveries`](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-funds-recovery-request) | Criar uma recuperação de fundos | | `GET` | [`/v1/dict/funds-recoveries/{id}`](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-funds-recovery-details) | Consultar uma recuperação de fundos | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](https://docs.lerian.studio/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`](https://docs.lerian.studio/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`](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph) | Ver o grafo de rastreamento | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports) | Listar os relatos de infração ligados | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/request-funds-recovery-refund) | Solicitar devoluções (o status deve ser `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](https://docs.lerian.studio/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": 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](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-funds-recovery-refunds.md). # 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`. | 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` | Um cash-out com `X-Purpose: INSTANT_PAYMENT_REFUND` para uma conta em outra instituição também precisa de `contestedMedRootTransactionId` no corpo: o `rootTransactionId` da recuperação de fundos contestada no MED. Depois que o plugin remove os espaços das pontas, o valor deve ter exatamente 32 letras, dígitos ou sublinhados. Um valor ausente recebe `400` `PIX-0481`. Um valor malformado recebe `400` `PIX-0482`. Os dois são recusados antes de qualquer movimentação de fundos. Uma devolução dentro da sua própria instituição e os outros propósitos ignoram o campo. ```json theme={null} POST /v1/transfers/cashout/process X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d X-Purpose: INSTANT_PAYMENT_REFUND { "initiationId": "019c96a0-0c82-7c3d-8dcc-c180868b45c4", "amount": "100.50", "contestedMedRootTransactionId": "E9999901012341234123412345678900" } ``` > [!WARNING] > > `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](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-a-pix-transfer.md) 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](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-an-infraction-report.md) e [o endpoint de listagem](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-infraction-reports.md) * **Solicitações de devolução**: [Consultar uma solicitação de devolução](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-a-refund-request.md) e [o endpoint de listagem](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-refund-requests.md) 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](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md) 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", "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):** ```json theme={null} { "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 *** > [!WARNING] > > Não use [Criar um relato de infração](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-an-infraction-report.md) nem [Encerrar um relato de infração](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/close-an-infraction-report.md) 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](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md): Devoluções parciais distribuídas e desbloqueio de devoluções travadas * [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md): Envelope de evento, novas tentativas e roteamento * [Domínios principais: MED](https://docs.lerian.studio/pt/interfaces/pix/main-domains-med.md): Conceitos de disputa e devolução do MED * [Referência da API](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-entry.md): Documentação completa da API This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.