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.
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).
Billing periods
When triggering a billing calculation, you specify the time window through the
period field. Fees Engine supports three formats:
| Format | Example | Window |
|---|---|---|
| Daily | 2026-03-15 | Start of that day → start of the next day (UTC) |
| Weekly | 2026-W13 | Monday 00:00 UTC of the ISO week → following Monday 00:00 UTC |
| Monthly | 2026-03 | First instant of the month → first instant of the next month (UTC) |
2026-03-15; a SaaS platform billed monthly would use 2026-03; a marketplace that settles weekly would use 2026-W13.
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.
flatFee
Applies a fixed fee amount. Behavior depends onisDeductibleFrom.
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
UseminimumAmount and maximumAmount to define when fees should apply.
For example: If the range is R 301 won’t trigger fees.
By account
The system checkswaivedAccounts. If the source is listed, it’s exempt from fees.
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 |
@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 |
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 |
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.
Billing calculations
Billing packages use a different calculation model than fee packages. Instead of evaluating individual transactions, they aggregate data over a billing period and return charge payloads for your orchestrator to execute. Billing supports three period formats: monthly (
YYYY-MM), weekly (YYYY-Www, e.g., 2026-W13), and daily (YYYY-MM-DD).
Volume billing calculation
Volume billing counts transactions matching aneventFilter (transaction route + status) within the billing period, then applies pricing based on the configured model.
The calculation follows this order:
- Count qualifying transactions in the period.
- Subtract the
freeQuotafrom the total count. - Apply pricing based on the
pricingModel(tieredorfixed). - Apply discounts from
discountTiersif the total volume meets any threshold.
Tiered pricing
Each tier defines a quantity range and a unit price. The engine applies the corresponding price for each unit within each range. Example: A billing package for boleto issuance with three tiers and a free quota of 50:| Range | Unit price |
|---|---|
| 1–500 | R$ 1.20 |
| 501–2,000 | R$ 0.80 |
| 2,001+ | R$ 0.45 |
- 50 exempt (free quota)
- 1,750 billable: 500 × R$ 1.20 + 1,250 × R$ 0.80 = R$ 1,600.00
- Discount tier applies (> 1,000 boletos → 5%): −R$ 80.00
- Total: R$ 1,520.00
Fixed pricing
A single unit price applies to all billable transactions regardless of volume. The free quota is still subtracted before calculation. Example: R$ 0.10 per Pix sent, no free quota:- 5,000 Pix transactions × R$ 0.10 = R$ 500.00
Count modes
ThecountMode field determines how transactions are grouped:
perRoute— Counts all matching transactions across the organization as a single total.perAccount— Counts transactions per individual account and applies pricing independently to each.
Maintenance billing calculation
Maintenance billing charges a fixed amount per active account in the billing period. The engine resolves the target accounts, filters for active status, and generates a single transaction payload. The result is a N:1 transaction:- Each active account appears as a debit entry (
source.from) for the configuredfeeAmount. - The
maintenanceCreditAccountreceives the full total as a single credit entry (distribute.to).
- 12,000 entries in
source.from, each debited R$ 9.90 - 1 entry in
distribute.tocredited R$ 118,800.00
All-or-nothing failure policy
If any billing package fails during a/billing/calculate call, the entire operation fails. No partial results are returned. The response includes which package and resource caused the failure, so you can fix and re-execute.