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

# Migrar as tarifas do Bank Transfer para o Midaz

> Mova os pacotes de tarifas do plugin-fees standalone para o Fees Engine do Midaz e passe o Bank Transfer 3.1.0 ou posterior para as tarifas do Midaz sem uma janela sem cobrança.

O Bank Transfer 3.0.x cobra tarifas pelo plugin de tarifas standalone, `plugin-fees`. O Bank Transfer 3.1.0 e posteriores podem cobrá-las pelo [Fees Engine](/pt/products/midaz/fees/fees-engine-overview) que roda dentro do Midaz 4.1.0 e posteriores. Esta página move seus pacotes de tarifas do plugin-fees para o Midaz. Em seguida, ela passa o Bank Transfer para o Midaz em uma ordem que mantém a cobrança de cada transferência.

Siga esta página quando todas estas condições forem verdadeiras:

* Você roda o Bank Transfer 3.0.x.
* Seus pacotes de tarifas ficam no plugin-fees.
* Você vai atualizar para o Bank Transfer 3.1.0 ou posterior e para o Midaz 4.1.0 ou posterior.

O Bank Transfer usa apenas os pacotes de tarifas do plugin-fees. Se você também mantém pacotes de faturamento no plugin-fees, recrie-os como [pacotes de faturamento](/pt/products/midaz/fees/using-fee-engine) do Midaz antes de desativar o plugin-fees. Esta página não faz o mapeamento deles.

<Note>
  O Lerian Console gerencia apenas pacotes de tarifas do Midaz. Ele não mostra os pacotes que ficam no plugin-fees. Veja [Console](#console).
</Note>

## Como o Bank Transfer escolhe quem cobra a tarifa

***

A partir da 3.1.0, a variável `MIDAZ_FEE_MODE` do Bank Transfer decide quem calcula e cobra a tarifa de cada transferência.

| Valor | Quem cobra a tarifa | API do Midaz em que o Bank Transfer lança |
| - | - | - |
| `legacy` | O plugin-fees, como no Bank Transfer 3.0.x | `/v1` |
| `native` | O Fees Engine do Midaz, a partir dos pacotes de tarifas do ledger | `/v2` |
| `auto` (padrão) | O Bank Transfer lê a versão do Midaz. Ele usa `native` no Midaz 4.1.0 ou posterior, e `legacy` em uma versão anterior. | `/v2` ou `/v1` |

* O Bank Transfer não inicia com nenhum outro valor.
* Com `auto`, o Bank Transfer lê a versão do Midaz de novo a cada `MIDAZ_FEE_MODE_REFRESH` (padrão `5m`). Quando não consegue ler a versão, ele mantém o modo que já tem, ou usa `legacy` se ainda não tem nenhum.
* O Bank Transfer fixa o modo de uma transferência P2P ou de um TED OUT em `/initiate`, e o de um TED IN quando o recebe. Cada etapa seguinte dessa transferência usa o mesmo modo: novas tentativas, confirmação, cancelamento e conciliação. Uma mudança de modo vale apenas para transferências novas.
* No modo `legacy`, `BTF_FEE_ENABLED` liga a integração com o plugin-fees. Com `false`, o padrão, o Bank Transfer não chama o plugin-fees, e cada transferência roda com tarifa 0.
* Defina `native` apenas no Midaz 4.1.0 ou posterior. O Midaz 4.0.x cobra tarifas sem marcar os lançamentos de tarifa, então o Bank Transfer não consegue ler a tarifa que cobrou.

<Warning>
  Não dependa de `auto` durante a migração. Com `auto`, o Bank Transfer 3.1.0 passa para `native` sozinho assim que lê o Midaz 4.1.0 ou posterior. As transferências novas passam então a usar os pacotes do Midaz. Se seus pacotes ainda estão apenas no plugin-fees, o Midaz não encontra nenhum pacote, e essas transferências ficam sem tarifa.

  No Bank Transfer 3.1.0, `BTF_FEE_ENABLED` não impede o Midaz de cobrar tarifas no modo `native`. Para parar uma tarifa, desabilite o pacote dela no Midaz com `enable: false`, ou exclua o pacote. O Midaz então também não cobra tarifa de uma transferência native que ele ainda não lançou.
</Warning>

## Antes de começar

***

Você precisa de:

* Midaz 4.1.0 ou posterior, ou um plano para atualizar para ele. Veja [Atualizando o Midaz](/pt/products/midaz/updating-midaz).
* Bank Transfer 3.1.0 ou posterior, ou um plano para atualizar para ele.
* Acesso à API do plugin-fees, para ler e estimar seus pacotes.
* Acesso à API de pacotes de tarifas do Midaz, ou à página [Pacotes de tarifas](/pt/products/midaz/fees/console/managing-fee-packages) do Console.
* Para cada ledger e tipo de transferência, a rota de transação do Midaz com que o Bank Transfer lança. A política de tenant `routing.ledger_bindings` informa essa rota. Veja [Roteamento do ledger](/pt/interfaces/ted-jd/ted-configuration#ledger-routing).
* Três permissões do Midaz para as credenciais do Midaz do Bank Transfer: o recurso `packages` com a ação `get`, o recurso `estimates` com a ação `post`, e o recurso `organizations` com a ação `get`. No modo single-tenant, essas são as credenciais de `MIDAZ_CLIENT_ID`. No modo multi-tenant, o Bank Transfer usa as credenciais do Midaz de cada tenant, então dê as três permissões à aplicação de cada tenant.

O modo `legacy` não usa essas permissões. No modo `native`, sem `packages`, cada iniciação de P2P e de TED OUT responde `503 BTF-2000`. Sem `estimates`, cada iniciação que corresponde a um pacote responde `503 BTF-2000`. A permissão `organizations` é necessária porque esta página define `MIDAZ_FEE_MODE=native` explicitamente: o Bank Transfer então faz uma leitura da lista de organizações do Midaz, para verificar a API `/v2`, antes de usar um conjunto de credenciais pela primeira vez. Com `auto`, ele não faz essa leitura. Sem `organizations`, o Bank Transfer no modo single-tenant não inicia, e no modo multi-tenant cada iniciação de P2P e de TED OUT daquele tenant responde `503 BTF-2000`.

Os exemplos abaixo usam estas variáveis de shell. Cada UUID é um exemplo. Use os valores do seu próprio ambiente.

O Bank Transfer acessa o ledger do Midaz em `MIDAZ_TRANSACTION_URL`, ou em `MIDAZ_BASE_URL` quando aquela não está definida. Ele remove um `/v1` ou `/v2` do fim desse endereço. Remova-o também em `MIDAZ_LEDGER_URL`, porque os paths abaixo já trazem a versão.

```bash theme={null}
# Addresses, as Bank Transfer has them.
FEES_BASE_URL="https://plugin-fees.example.com"    # FEES_BASE_URL
MIDAZ_LEDGER_URL="https://midaz.example.com"

# Two different bearers. They are not interchangeable.
FEES_BEARER_TOKEN="..."                            # for plugin-fees
MIDAZ_BEARER_TOKEN="..."                           # for the ledger

MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"
```

## Mapear um pacote do plugin-fees para um pacote do Midaz

***

Migre apenas os pacotes que estão habilitados no plugin-fees. Deixe os desabilitados de fora. O Midaz recusa um pacote cuja faixa de valores se sobrepõe a outro pacote com a mesma rota e o mesmo segmento, e ele conta também os pacotes desabilitados (erro `0199`). Então uma cópia desabilitada pode bloquear um pacote de que você precisa.

As regras de tarifa mantêm os nomes dos campos e o formato JSON. Três coisas mudam: onde vai a organização, onde vai o ledger e o que `transactionRoute` contém.

| plugin-fees | Midaz | O que fazer |
| - | - | - |
| Header `X-Organization-Id` | `{organization_id}` na URL | Envie a organização no path. |
| `ledgerId` no corpo | `{ledger_id}` na URL | Envie o ledger no path. |
| `transactionRoute` | `transactionRoute` | Troque o valor. Veja [Rota de transação](#transaction-route). |
| `feeGroupLabel`, `description` | Os mesmos campos | Copie. |
| `segmentId` | `segmentId` | Copie-o ou deixe-o de fora, como diz [Escopo do pacote](#package-scope). Deixe-o de fora de cada pacote de TED IN. |
| `minimumAmount`, `maximumAmount` | Os mesmos campos | Copie. |
| `waivedAccounts` | `waivedAccounts` | Copie. Os dois aceitam aliases de conta e a forma `segment:<segment-uuid>`. |
| `enable` | `enable` | Migre apenas pacotes com `true`. Crie cada um com `false`. Você o habilita quando passa para `native`. |
| `feeLabel`, `calculationModel`, `referenceAmount`, `priority`, `isDeductibleFrom` de cada tarifa | Os mesmos campos | Copie. |
| `creditAccount` de cada tarifa | `creditAccount` | Copie. A conta precisa existir no ledger. O Midaz confere isso quando você cria o pacote. |
| `routeFrom`, `routeTo` de cada tarifa | Os mesmos campos | O Midaz grava o valor como a rota de operação do lançamento de tarifa. Use o ID de uma rota de operação do Midaz, ou deixe o campo de fora. No modo `legacy`, o Bank Transfer descartava um valor que não era um ID de rota. |
| `id`, `createdAt`, `updatedAt`, `deletedAt` | Valores novos | Deixe-os de fora. O Midaz atribui um ID novo. Registre qual pacote do plugin-fees cada pacote do Midaz substitui. |
| Sem equivalente | `metadataSelector` (Midaz 4.2.0 ou posterior) | Deixe-o de fora. A prévia de tarifa do Bank Transfer não o lê, então a tarifa mostrada na iniciação pode ser diferente da tarifa que o Midaz cobra. |

O Midaz rejeita um campo que não conhece. Não envie nenhum destes: `ledgerId`, `id`, `createdAt`, `updatedAt` e `deletedAt`.

Um TED OUT cobra a tarifa por cima do valor. No modo `native`, o Bank Transfer recusa um TED OUT com `422 BTF-3002` quando o pacote que corresponde a ele tem uma tarifa com `isDeductibleFrom: true`.

<h3 id="transaction-route">
  Rota de transação
</h3>

O plugin-fees compara `transactionRoute` com um nome que o Bank Transfer envia: `ted_out`, `ted_in` ou `p2p`. O Midaz o compara com o `routeId` da transação, que é o ID de uma rota de transação do Midaz. O Midaz aceita apenas um UUID nesse campo.

Para cada pacote, use a rota de transação que `routing.ledger_bindings` informa para o ledger e o tipo de transferência do pacote.

<Warning>
  Um pacote do Midaz cobra cada transação `/v2` do ledger dele que corresponde ao escopo dele, vinda de qualquer produto, não apenas as transferências do Bank Transfer. Um pacote sem `transactionRoute` corresponde a todas as transações. Um pacote com rota corresponde a todas as transações lançadas com essa rota. Dê a cada pacote do Bank Transfer a rota de transação dele, e não use essas rotas de transação em outros produtos.

  Um ledger cujo vínculo usa `mode: omit` não tem pacote seguro: o único que pode corresponder às transferências dele não tem rota, então cobra cada transação `/v2` do ledger. Dê a esse vínculo a rota de transação do Midaz de cada tipo de transferência na página [Rotas Contábeis](/pt/interfaces/ted-jd/console/bt-accounting-routes) do Console, e confira a **Prontidão para a virada** nela. Isso muda a contabilização de cada lançamento do Bank Transfer nesse ledger. Faça isso depois do passo 2, quando o Midaz já rodar a 4.1.0 ou posterior, e antes da troca.
</Warning>

<h3 id="package-scope">
  Escopo do pacote
</h3>

O plugin-fees e o Midaz selecionam o pacote de uma transferência de jeitos diferentes, então uma cópia exata pode cobrar uma tarifa diferente. Aplique estas regras aos pacotes habilitados de cada ledger:

* **O ledger tem um pacote habilitado.** O plugin-fees o aplica a cada transferência dentro da faixa de valores dele, seja P2P, TED OUT ou TED IN. Ele ignora o `transactionRoute` e o `segmentId` desse pacote. No Midaz, crie uma cópia para cada tipo de transferência que ele cobrava, cada uma com a rota de transação desse tipo, e sem `segmentId`.
* **Uma rota tem um pacote.** Quando o ledger tem mais de um pacote habilitado, o plugin-fees aplica o único pacote de uma rota a cada transferência dessa rota, dentro da faixa de valores dele. Ele ignora o `segmentId` desse pacote. Crie o pacote do Midaz sem `segmentId`.
* **Uma rota tem vários pacotes.** O plugin-fees então escolhe pelo segmento do remetente. Um remetente com segmento recebe apenas um pacote com esse segmento. Um remetente sem segmento recebe apenas um pacote sem segmento. Mantenha cada `segmentId`. O Midaz também aplica um pacote sem segmento a um remetente que tem segmento, quando nenhum pacote desse segmento cobre o valor. Se a rota tem um pacote sem segmento, decida qual comportamento você quer. Quando cada tarifa desse pacote é cobrada por cima do valor (`isDeductibleFrom: false`), você pode manter o comportamento do plugin-fees. Adicione `segment:<segment-uuid>` ao `waivedAccounts` desse pacote para cada segmento do ledger, e para cada segmento que você criar depois. O Midaz então não cobra nenhuma das tarifas dele de um remetente nesses segmentos. Em uma tarifa descontada do valor, a isenção também isenta um destinatário nesses segmentos, então não a use nesse caso. Para um pacote assim, os mecanismos não podem coincidir. Decida se um remetente cujo segmento não tem pacote próprio para esse valor paga esse pacote no Midaz, ou se você o deixa de fora, e então um remetente sem segmento não paga nenhuma das tarifas dele.
* **TED IN.** Para um TED IN, o Bank Transfer enviava ao plugin-fees o segmento da conta do destinatário. O Midaz lê o segmento das contas de origem e ignora a conta externa, que é a única origem de um TED IN. Então um pacote do Midaz com `segmentId` nunca corresponde a um TED IN. Crie cada pacote de TED IN sem `segmentId`. Se o ledger tem mais de um pacote de TED IN no plugin-fees, o plugin-fees cobrava de um destinatário com segmento apenas um pacote com esse segmento, e de um destinatário sem segmento apenas um pacote sem segmento. O Midaz não vê o segmento do destinatário, e aplica os pacotes sem segmento a cada destinatário. Decida o preço de TED IN que vale para cada destinatário.
* **Um pacote sem rota.** Quando o ledger tem mais de um pacote habilitado, o plugin-fees nunca aplicava um pacote sem rota a uma transferência do Bank Transfer, porque o Bank Transfer sempre envia uma rota. Deixe-o de fora.
* **Dois pacotes que correspondem.** O Midaz seleciona o pacote que atende ao maior número de restrições. Quando dois pacotes correspondem igualmente, o Midaz recusa a transação com o erro `0198`. Na iniciação, o Bank Transfer responde `422 BTF-2005`.

## Migrar passo a passo

***

<Steps>
  <Step title="Fixe o modo legacy">
    Defina `MIDAZ_FEE_MODE=legacy` no ambiente do Bank Transfer. No Helm chart, a chave é `bankTransfer.configmap.MIDAZ_FEE_MODE`, e o chart usa `auto` quando a chave não está definida. O Bank Transfer 3.0.x ignora a variável, então você pode defini-la antes da atualização.

    Confira o valor que o seu deploy gera antes de atualizar, por exemplo com `helm template` ou `helm diff`. Uma atualização gradual não para depois do primeiro pod, a menos que você a pause.

    Mantenha `BTF_FEE_ENABLED=true` e as variáveis `FEES_*` como estão.
  </Step>

  <Step title="Atualize o Bank Transfer e depois o Midaz">
    Atualize o Bank Transfer para 3.1.0 ou posterior. Espere até que cada pod do Bank Transfer rode a 3.1.0 ou posterior. Uma versão anterior não consegue liquidar uma transferência que o Bank Transfer criou no modo `native`.

    Confira no log de cada pod a linha `midaz: fee mode resolved` com `feeMode=legacy` e `source=config`. No modo single-tenant, um pod a registra no boot. No modo multi-tenant, ele a registra para cada tenant na primeira transferência desse tenant. `source=config` prova que a fixação funciona. Confira isso enquanto o Midaz ainda roda uma versão anterior à 4.1.0. Nela, `auto` também resolve para `legacy`, então uma transferência que paga a tarifa do plugin-fees não prova a fixação.

    Atualize o Midaz para 4.1.0 ou posterior.

    Faça uma transferência pequena. Confirme que o plugin-fees ainda cobra a tarifa dele.
  </Step>

  <Step title="Recrie cada pacote habilitado no Midaz">
    Liste os pacotes habilitados de cada ledger no plugin-fees. Cada resposta traz uma página, e o `total` dela conta apenas os itens dessa página. Leia a próxima página até que uma página traga menos itens do que `limit`. A lista deixa de fora os pacotes excluídos.

    ```bash theme={null}
    curl -s "$FEES_BASE_URL/v1/packages?ledgerId=$MIDAZ_LEDGER_ID&enable=true&limit=100&page=1" \
      -H "Authorization: Bearer $FEES_BEARER_TOKEN" \
      -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID"
    ```

    Crie cada pacote no Midaz com o mapeamento e as regras de escopo acima. Defina `enable` como `false`. Guarde a lista dos pacotes que você cria: você habilita exatamente esses na troca. Este exemplo recria uma tarifa fixa de TED OUT. O `transactionRoute` dele é a rota de transação de TED OUT do vínculo do ledger.

    ```bash theme={null}
    curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/packages" \
      -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{
        "feeGroupLabel": "TED OUT fee",
        "description": "Fee on outgoing TEDs",
        "transactionRoute": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
        "minimumAmount": "0.01",
        "maximumAmount": "1000000.00",
        "fees": {
          "tedOutFee": {
            "feeLabel": "TED OUT fee",
            "calculationModel": {
              "applicationRule": "flatFee",
              "calculations": [{ "type": "flat", "value": "5.00" }]
            },
            "referenceAmount": "originalAmount",
            "priority": 1,
            "isDeductibleFrom": false,
            "creditAccount": "fees-revenue"
          }
        },
        "enable": false
      }'
    # -> {"id": "..."}  this is the Midaz package ID
    ```

    Você também pode criar os pacotes na página [Pacotes de tarifas](/pt/products/midaz/fees/console/managing-fee-packages) do Console.
  </Step>

  <Step title="Compare as tarifas dos dois mecanismos">
    Para cada pacote, estime a mesma transação no plugin-fees e no Midaz. Compare os valores das tarifas. Eles devem ser iguais. Use valores nas duas pontas da faixa do pacote, e um valor no meio. Para um pacote que tem as isenções de segmento de [Escopo do pacote](#package-scope), use um remetente fora desses segmentos. O Midaz isenta um remetente neles por definição, e o plugin-fees não.

    ```bash theme={null}
    TRANSACTION='{
      "send": {
        "asset": "BRL",
        "value": "1500.00",
        "source": { "from": [{ "accountAlias": "@sender", "amount": { "asset": "BRL", "value": "1500.00" } }] },
        "distribute": { "to": [{ "accountAlias": "@external/BRL", "amount": { "asset": "BRL", "value": "1500.00" } }] }
      }
    }'

    # plugin-fees: the plugin-fees package ID, and the ledger in the body
    curl -s -X POST "$FEES_BASE_URL/v1/estimates" \
      -H "Authorization: Bearer $FEES_BEARER_TOKEN" \
      -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID" \
      -H 'Content-Type: application/json' \
      -d '{ "packageId": "0198f1a2-6c3d-7e4f-8a9b-1c2d3e4f5a6b", "ledgerId": "'"$MIDAZ_LEDGER_ID"'", "transaction": '"$TRANSACTION"' }'

    # Midaz: the Midaz package ID, and the ledger in the URL
    curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/estimates" \
      -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
      -H 'Content-Type: application/json' \
      -d '{ "packageId": "0199b7d2-4f5e-7a6b-8c9d-2e3f4a5b6c7d", "transaction": '"$TRANSACTION"' }'
    ```

    Na resposta do Midaz, cada lançamento de tarifa tem `"feeLeg": "true"` no seu `metadata`. Você também pode usar a [Calculadora de tarifas](/pt/products/midaz/fees/console/managing-fee-calculations) do Console.

    Uma estimativa calcula o único pacote que você informa. Ela não confere `transactionRoute` nem `segmentId`, então não mostra qual pacote uma transferência recebe. O próximo passo testa isso.
  </Step>

  <Step title="Ensaie a seleção em homologação">
    Rode os passos 1 a 4 em homologação primeiro, com os mesmos pacotes. Depois teste qual pacote cada transferência recebe, antes de fazer a troca em produção:

    1. Com `legacy`, chame `POST /v1/transfers/initiate` para cada caso: P2P e TED OUT, de um remetente em cada segmento do ledger e de um remetente sem segmento, com valores nas duas pontas da faixa de cada pacote. Registre `feeAmount` e `packageAppliedId` de cada resposta. Não processe essas iniciações. Uma iniciação não lança nada no Midaz. Ela grava uma linha em `payment_initiations` que expira em `expiresAt`, guarda um fingerprint de duplicidade por 300 segundos por padrão, e envia um evento `payment_initiation.created` aos seus consumidores de webhook e de eventos. Uma iniciação de TED OUT fora do horário de funcionamento responde `422 BTF-0010`.
    2. Passe a homologação para `native`, como no próximo passo.
    3. Repita as mesmas iniciações. Compare cada `feeAmount`. `packageAppliedId` agora indica o pacote do Midaz. Confira que é o pacote que substitui o do plugin-fees. Uma iniciação idêntica dentro dessa janela de duplicidade responde `409 BTF-0012`, então espere a janela passar.
    4. O TED IN não tem iniciação. Em cada modo, receba um TED IN pequeno para um destinatário em cada segmento e para um destinatário sem segmento. Compare as tarifas.

    Espere uma diferença apenas onde [Escopo do pacote](#package-scope) diz que os mecanismos não podem coincidir, e apenas a que você escolheu ali. Corrija cada outra diferença nos pacotes do Midaz, e repita os casos.
  </Step>

  <Step title="Passe o Bank Transfer para native">
    Antes da troca, rode em produção os casos de iniciação de P2P e TED OUT do passo 5, com `legacy`. Use contas de teste próprias, uma em cada segmento e uma sem segmento. Registre cada `feeAmount`. O passo 5 diz o que uma iniciação grava.

    1. Dê às credenciais do Midaz do Bank Transfer as permissões `packages` (`get`), `estimates` (`post`) e `organizations` (`get`).
    2. Habilite cada pacote do Midaz que você criou no passo 3. Envie `"enable": true` com [Atualizar um Pacote](/pt/reference/products/midaz/v2/update-package). Nenhuma iniciação testa um TED IN, então antes compare o `transactionRoute` de cada pacote de TED IN com a **Rota de Transação** do vínculo `TED_IN` do ledger dele, na página [Rotas Contábeis](/pt/interfaces/ted-jd/console/bt-accounting-routes) do Console.
    3. Defina `MIDAZ_FEE_MODE=native`.
    4. Reinicie cada pod do Bank Transfer.

    Logo depois do reinício, rode os mesmos casos de novo, com as mesmas contas. Compare cada `feeAmount`, e confira cada `packageAppliedId`. Espere uma diferença apenas onde [Escopo do pacote](#package-scope) diz que os mecanismos não podem coincidir, e apenas a que você escolheu ali. Uma iniciação idêntica dentro da janela de duplicidade responde `409 BTF-0012`, então espere a janela passar entre as duas rodadas. Uma iniciação não lança nada no Midaz, então esses casos mostram uma rota ou um ID de segmento errado sem mover dinheiro.

    Se aparecer outra diferença, faça o [rollback](#roll-back). Corrija as tarifas ou a faixa de valores de um pacote com Atualizar um Pacote. Atualizar um Pacote não muda `transactionRoute` nem `segmentId`, então, para uma rota ou um segmento errado, crie um pacote corrigido com `enable: false`, e exclua o errado apenas depois que as transferências native que o usaram terminarem. Esta consulta lista as transferências criadas no modo `native` desde o início do reinício. Confira a tarifa de cada uma manualmente.

    ```sql theme={null}
    SELECT id, type, status, created_at FROM transfers
     WHERE ledger_fee_mode = 'native'
       AND created_at >= '2026-10-09 14:00:00-03';  -- just before the restart began
    ```

    As transferências novas agora usam as tarifas do Midaz. Uma transferência P2P ou um TED OUT iniciados antes do reinício, e um TED IN recebido antes dele, mantêm o modo `legacy` até terminarem.
  </Step>

  <Step title="Confira transferências reais">
    Faça uma transferência P2P ou um TED OUT pequenos. Confira a tarifa que o Bank Transfer mostra na iniciação. Confira a tarifa que ele registra na transferência. As duas devem bater com a tarifa que o plugin-fees cobrava antes, exceto por uma diferença que você escolheu em [Escopo do pacote](#package-scope).

    Confira do mesmo jeito o primeiro TED IN que chegar depois da troca.

    No Midaz, o metadata de cada transação tem `packageAppliedID`. Ele é o ID do pacote do Midaz que cobrou a tarifa.
  </Step>

  <Step title="Desative o plugin-fees">
    Mantenha o plugin-fees rodando enquanto esta consulta retornar linhas. No modo multi-tenant, rode-a no banco do Bank Transfer de cada tenant.

    ```sql theme={null}
    SELECT id, status FROM transfers
     WHERE type = 'TED_IN' AND ledger_fee_mode = 'legacy'
       AND status NOT IN ('COMPLETED', 'REJECTED', 'FAILED', 'CANCELLED');
    ```

    Esses são os TED INs recebidos antes da troca. Quando o Bank Transfer retoma um deles, ele pede a tarifa dele ao plugin-fees. Se o plugin-fees estiver parado, o Bank Transfer credita o destinatário sem tarifa. Quando `fees.fail_closed_default` é `true`, ele devolve a TED ao remetente, a menos que o Bank Transfer não consiga ler essa política.

    Depois, faça o backup do banco MongoDB do plugin-fees e pare o plugin-fees. A partir daí, você não pode fazer o [rollback](#roll-back).

    Mantenha `MIDAZ_FEE_MODE=native`. Com `auto`, um pod que não consegue ler a versão do Midaz inicia no modo `legacy`, e o `legacy` precisa do plugin-fees.
  </Step>
</Steps>

<h2 id="roll-back">
  Rollback
</h2>

***

Você pode voltar para o plugin-fees enquanto o plugin-fees ainda roda com os pacotes dele sem mudanças:

1. Defina `MIDAZ_FEE_MODE=legacy`.
2. Reinicie cada pod do Bank Transfer.

As transferências novas voltam então a usar o plugin-fees. Isso exige `BTF_FEE_ENABLED=true` e as variáveis `FEES_*` ainda no lugar.

As transferências criadas no modo `native` mantêm esse modo. O Bank Transfer as termina na API `/v2` do Midaz, e o Midaz cobra as tarifas delas quando as lança. Mantenha os pacotes do Midaz habilitados até que cada transferência native termine.

Mantenha o Bank Transfer na 3.1.0 ou posterior enquanto alguma transferência criada no modo `native` ainda estiver aberta. Uma versão anterior liquida essa transferência em `/v1`, então a tarifa dela não é cobrada ou não é registrada.

<h2 id="console">
  Console
</h2>

***

As páginas do Fees Engine no Console, [Pacotes de tarifas](/pt/products/midaz/fees/console/managing-fee-packages) e [Calculadora de tarifas](/pt/products/midaz/fees/console/managing-fee-calculations), trabalham apenas com pacotes de tarifas do Midaz. Elas não leem o plugin-fees.

## Veja também

***

* [O que é o Fees Engine?](/pt/products/midaz/fees/fees-engine-overview)
* [Usando o Fees Engine](/pt/products/midaz/fees/using-fee-engine)
* [Estimar as tarifas de uma transação](/pt/reference/products/midaz/v2/estimate-fee-calculation)
* [Configuração do Bank Transfer](/pt/interfaces/ted-jd/ted-configuration)
* [Variáveis de ambiente do Bank Transfer](/pt/interfaces/ted-jd/ted-environment-variables)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.