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+scaleformat).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: eitheroriginalAmountorafterFeesAmount.priority: defines the order of application. Priority 1 must always useoriginalAmount.
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.00Since 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.
isDeductibleFrom | Formula | Total Fee |
|---|---|---|
false | referenceAmount + fee | R$ 130.00 |
true | referenceAmount - fee | R$ 100.00 |
percentual
Applies a fee as a percentage of the reference amount.
Example
- Value: 30%.
- Reference amount: R$ 389.50.
isDeductibleFrom | Formula | Total Fee |
|---|---|---|
false | referenceAmount * value | R$ 116.85 |
true | referenceAmount - (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
| Account | Share | Amount |
|---|---|---|
| @account1 | 25% | R$ 1,000 |
| @account2 | 25% | R$ 1,000 |
| @account3 | 40% | R$ 1,600 |
| @account4 | 10% | R$ 400 |
Fixed fee distribution
Formula:
fixed Fee × participation %
| Account | Fee Share | Total |
|---|---|---|
| @account1 | R$ 3.75 | R$ 1,003.75 |
| @account2 | R$ 3.75 | R$ 1,003.75 |
| @account3 | R$ 6.00 | R$ 1,606.00 |
| @account4 | R$ 1.50 | R$ 401.50 |
Proportional tax
Formula:
account amount × tax %
| Account | Tax | Total w/ Tax |
|---|---|---|
| @account1 | R$ 40.00 | R$ 1,040.00 |
| @account2 | R$ 40.00 | R$ 1,040.00 |
| @account3 | R$ 64.00 | R$ 1,664.00 |
| @account4 | R$ 16.00 | R$ 416.00 |
Final amount per account
Formula:
principal + fee + tax
| Account | Fee | Tax | Final Total |
|---|---|---|---|
| @account1 | R$ 3.75 | R$ 40.00 | R$ 1,043.75 |
| @account2 | R$ 3.75 | R$ 40.00 | R$ 1,043.75 |
| @account3 | R$ 6.00 | R$ 64.00 | R$ 1,670.00 |
| @account4 | R$ 1.50 | R$ 16.00 | R$ 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.
TipHierarchy: 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 |
|---|---|---|
| @account1 | 15% | R$ 600 |
| @account2 | 35% | R$ 1,400 |
| @account3 | 40% | R$ 1,600 |
| @account4 | 10% | R$ 400 |
Fixed fee applied only to @account3 and @account4.
Result after Admin Fee (proportional)
| Account | Admin Fee | Total |
|---|---|---|
| @account1 | Exempt | R$ 600 |
| @account2 | Exempt | R$ 1,400 |
| @account3 | R$ 12.80 | R$ 1,612.80 |
| @account4 | R$ 3.20 | R$ 403.20 |
Total send value increases to R$4,016.
IOF deduction (recipient)
| Recipient | % | Gross | IOF (6%) | Net |
|---|---|---|---|---|
| @donation1 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
| @donation2 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
| @donation3 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
| @donation4 | 25% | R$ 1,000 | R$ 60 | R$ 940 |
ImportantFees 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.
Updated 3 days ago