Migrate Bank Transfer fees to Midaz

• You run Bank Transfer 3.0.x.
• Your fee packages live in plugin-fees.
• You upgrade to Bank Transfer 3.1.0 or later and to Midaz 4.1.0 or later.

​

How Bank Transfer chooses who charges the fee

• Bank Transfer does not start with any other value.
• Under auto, Bank Transfer reads the Midaz version again every MIDAZ_FEE_MODE_REFRESH (default 5m). When it cannot read the version, it keeps the mode it has, or uses legacy if it has none.
• Bank Transfer fixes the mode of a P2P transfer or TED OUT at /initiate, and of a TED IN when it receives it. Every later step of that transfer uses the same mode: retries, confirmation, cancellation and reconciliation. A change of mode applies to new transfers only.
• In legacy mode, BTF_FEE_ENABLED turns the plugin-fees integration on. With false, the default, Bank Transfer does not call plugin-fees, and every transfer runs with fee 0.
• Set native only on Midaz 4.1.0 or later. Midaz 4.0.x charges fees without marking the fee entries, so Bank Transfer cannot read the fee that it charged.

​

Before you start

• Midaz 4.1.0 or later, or a plan to upgrade to it. See Updating Midaz.
• Bank Transfer 3.1.0 or later, or a plan to upgrade to it.
• Access to the plugin-fees API, to read and estimate your packages.
• Access to the Midaz fee package API, or to the Console Fee Packages page.
• For each ledger and transfer type, the Midaz transaction route that Bank Transfer posts with. The tenant policy routing.ledger_bindings names it. See Ledger routing.
• Three Midaz permissions for the Midaz credentials of Bank Transfer: the resource packages with action get, the resource estimates with action post, and the resource organizations with action get. In single-tenant mode, these are the credentials of MIDAZ_CLIENT_ID. In multi-tenant mode, Bank Transfer uses the Midaz credentials of each tenant, so grant all three permissions to the application of each tenant.

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

​

Map a plugin-fees package to a Midaz package

​

Transaction route

​

Package scope

• The ledger has one enabled package. plugin-fees applies it to every transfer in its amount range, P2P, TED OUT and TED IN alike. It ignores the transactionRoute and the segmentId of that package. In Midaz, create one copy for each transfer type that it charged, each with the transaction route of that type, and without segmentId.
• A route has one package. When the ledger has more than one enabled package, plugin-fees applies the only package of a route to every transfer on that route, inside its amount range. It ignores the segmentId of that package. Create the Midaz package without segmentId.
• A route has several packages. plugin-fees then picks by the segment of the sender. A sender with a segment gets only a package with that segment. A sender with no segment gets only a package with no segment. Keep each segmentId. Midaz also applies a package with no segment to a sender who has a segment, when no package of that segment covers the amount. If the route has a package with no segment, decide which behavior you want. When every fee of that package is charged on top of the amount (isDeductibleFrom: false), you can keep the plugin-fees behavior. Add segment:<segment-uuid> to the waivedAccounts of that package for every segment of the ledger, and for every segment that you create later. Midaz then charges none of its fees to a sender in those segments. On a fee taken out of the amount, the waiver also exempts a recipient in those segments, so do not use it there. For such a package, the engines cannot match. Decide whether a sender whose segment has no package of its own for that amount pays it in Midaz, or whether you leave it out, so that a sender with no segment pays none of its fees.
• TED IN. For a TED IN, Bank Transfer sent plugin-fees the segment of the recipient account. Midaz reads the segment from the source accounts, and it skips the external account, which is the only source of a TED IN. So a Midaz package with a segmentId never matches a TED IN. Create every TED IN package without segmentId. If the ledger has more than one TED IN package in plugin-fees, plugin-fees charged a recipient with a segment only a package with that segment, and a recipient with no segment only a package with no segment. Midaz cannot see the segment of the recipient, and it applies the packages with no segment to every recipient. Decide the TED IN price that applies to every recipient.
• A package with no route. When the ledger has more than one enabled package, plugin-fees never applied a package with no route to a Bank Transfer transfer, because Bank Transfer always sends a route. Leave it out.
• Two packages that match. Midaz selects the package that matches the most constraints. When two packages match equally, Midaz refuses the transaction with error 0198. At initiation, Bank Transfer answers 422 BTF-2005.

​

Migrate step by step

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"

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

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"' }'

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

SELECT id, status FROM transfers
 WHERE type = 'TED_IN' AND ledger_fee_mode = 'legacy'
   AND status NOT IN ('COMPLETED', 'REJECTED', 'FAILED', 'CANCELLED');

​

Roll back

1. Set MIDAZ_FEE_MODE=legacy.
2. Restart every Bank Transfer pod.

​

Console

​

See also

• What is Fees Engine?
• Using Fees Engine
• Estimate transaction fees
• Bank Transfer configuration
• Bank Transfer environment variables