Fees Engine calculations

Fees Engine automates the calculation, allocation, and exemption of fees in transactions. It ensures accuracy, traceability, and compliance while giving you the flexibility to model complex business rules and accounting routes.


Numeric values (string)


All financial values in Fees Engine must be expressed as a string, using the numeric type. This ensures high-precision decimal handling for assets like BRL or BTC, and prevents rounding errors during calculations, splits, or exemptions.

❗️

Important

  • Required: Midaz v3.x.x (uses numeric).
  • Incompatible: Midaz v2.x.x (deprecated amount + scale format).

Clients using Midaz v2.x.x must upgrade to v3.x.x to ensure proper integration and functionality with Fees Engine.

Example:

"value": "12.50"

Fee calculation rules


Each fee uses an applicationRule to define how it's calculated. You can choose from three rule types:

You can combine different rules in a single package to match your use case.

Other key fields:

  • isDeductibleFrom: defines if the fee is deducted from the sender or the receiver.
  • referenceAmount: either originalAmount or afterFeesAmount.
  • priority: defines the order of application. Priority 1 must always use originalAmount.

maxBetweenTypes

Applies whichever is greater: a flat or percentage-based fee.

Example

  • Flat fee value: R$5.
  • Percentual fee: 2%.
  • Reference amount: R$1,000.
rate = 1000 * 0.02 = R$ 20.00

Since R$ 20 is greater than R$ 5, the percentage-based fee is applied.


flatFee

Applies a fixed fee amount. Behavior depends on isDeductibleFrom.

Example

  • Flat fee: R$15.
  • Reference amount: R$115.
isDeductibleFromFormulaTotal Fee
falsereferenceAmount + feeR$ 130.00
truereferenceAmount - feeR$ 100.00

percentual

Applies a fee as a percentage of the reference amount.

Example

  • Value: 30%.
  • Reference amount: R$ 389.50.
isDeductibleFromFormulaTotal Fee
falsereferenceAmount * valueR$ 116.85
truereferenceAmount - (referenceAmount * value)R$ 272.65

Fee splitting


When a transaction has multiple source accounts, Fees Engine splits fees proportionally.

Example

  • Total amount: R$4,000.00
  • Fixed fee: R$15.00
  • Tax: 4%
  • isDeductibleFrom: false

Participation %

Formula: (Account Amount ÷ Total Amount) × 100

AccountShareAmount
@account125%R$ 1,000
@account225%R$ 1,000
@account340%R$ 1,600
@account410%R$ 400

Fixed fee distribution

Formula: fixed Fee × participation %

AccountFee ShareTotal
@account1R$ 3.75R$ 1,003.75
@account2R$ 3.75R$ 1,003.75
@account3R$ 6.00R$ 1,606.00
@account4R$ 1.50R$ 401.50

Proportional tax

Formula: account amount × tax %

AccountTaxTotal w/ Tax
@account1R$ 40.00R$ 1,040.00
@account2R$ 40.00R$ 1,040.00
@account3R$ 64.00R$ 1,664.00
@account4R$ 16.00R$ 416.00

Final amount per account

Formula: principal + fee + tax

AccountFeeTaxFinal Total
@account1R$ 3.75R$ 40.00R$ 1,043.75
@account2R$ 3.75R$ 40.00R$ 1,043.75
@account3R$ 6.00R$ 64.00R$ 1,670.00
@account4R$ 1.50R$ 16.00R$ 417.50

Validations

  • Total shares = 100%
  • Fee split matches flat fee
  • Tax split = 4%
  • Total sent = R$ 4,175.00

Fee exemptions: rules & hierarchy


By transaction amount

Use minimumAmount and maximumAmount to define when fees should apply.

For example: If the range is R$ 0–300, a transaction of R$ 301 won’t trigger fees.


By account

The system checks waivedAccounts. If the source is listed, it’s exempt from fees.

👍

Tip

Hierarchy: Value range check > then account exemption


Mixed example: fee exemptions and proportional fee splitting


Let’s look at an example of a package that includes accounts with fee exemptions and requires splitting fees proportionally.

Scenario

We’re processing a transaction of R$ 4,000, which includes:

  • A fixed fee of R$ 16.
  • Only some accounts are subject to the fixed fee
  • An IOF tax of 6% to be deducted.

Split on the source side

Source Account%Proportional Value
@account115%R$ 600
@account235%R$ 1,400
@account340%R$ 1,600
@account410%R$ 400

Fixed fee applied only to @account3 and @account4.


Result after Admin Fee (proportional)

AccountAdmin FeeTotal
@account1ExemptR$ 600
@account2ExemptR$ 1,400
@account3R$ 12.80R$ 1,612.80
@account4R$ 3.20R$ 403.20

Total send value increases to R$4,016.


IOF deduction (recipient)

Recipient%GrossIOF (6%)Net
@donation125%R$ 1,000R$ 60R$ 940
@donation225%R$ 1,000R$ 60R$ 940
@donation325%R$ 1,000R$ 60R$ 940
@donation425%R$ 1,000R$ 60R$ 940

❗️

Important

Fees are credited to the accounts defined in each fee’s creditAccount.



Repeating decimals


When a fee split results in repeating decimals (e.g., 0.3333...), Fees Engine automatically adjusts the first or largest value by a cent to ensure the total remains exact. This avoids rounding drift and keeps your ledger consistent.