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
: eitheroriginalAmount
orafterFeesAmount
.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.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.
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 14 days ago