A Fee Package groups fee rules and defines when they apply to Transactions.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.
Before you start
- The Fees Engine plugin must be enabled in Midaz module settings.
- You need an existing Ledger and at least one Account that can receive fee amounts.
- If the package should apply only to a specific route or segment, create those records first.
Create the Fee Package
The New Fee Package form will open with multiple sections to configure.
Configure the Amount Range section
Transactions outside this range will not have fees applied from this package.
Select one of the options in the Add Fee section:
Flat Fee- Fixed amount regardless of transaction value.Percentage- Percentage of the transaction amount.Max Between Types- Higher value between flat and percentage.
(Optional) You can add another fee rule if needed. To do so, select a new fee type and fill the information.
(Optional) Configure Account Waivers section:
- Add account aliases that should be exempt from fees in this package
- Click Add to add each waived account
Field guide
Basic Information
| Field | Description | Example |
|---|---|---|
| Fee Package Name | Required package name. Use a name that describes the charge model. | Standard Transfer Fee |
| Description | An explanation of when and why the package applies. | Fixed fee for standard transfers |
| Transaction Route | Optional route filter for the package. | Pix Transfer Route |
| Ledger ID | The unique identifier of the Ledger where this package applies. | Brazil Payments Ledger |
| Segment ID | Optional segment filter for targeted fees. | Retail Customers |
| Minimum Amount | Lowest transaction amount eligible for the package. | 10.00 |
| Maximum Amount | Highest transaction amount eligible for the package. | 500.00 |
Fee Rules
Every fee inside a package has a Priority (1 = applied first). The fee with priority1 must use Original Amount as Reference Amount.
Flat Fee
A fixed amount applied to the Transaction regardless of its value.| Field | Description | Example |
|---|---|---|
| Amount | The fixed amount charged for this fee. Must be a positive number. | 5.00 |
| Fee Name | Unique identifier for this fee, used as the JSON object key. Must start with a letter or underscore and contain only letters, numbers, or _. | taxaAdm |
| Reference Amount | Base used by the calculation: Original Amount (transaction value as sent) or After Fees Amount (value after previous fees in the package). | Original Amount |
| Credit Account ID | Alias of the account that receives the fee amount. | @fees_transfers |
| Route From | Optional. Name or UUID of the source route for this fee operation. | payments_in |
| Route To | Optional. Name or UUID of the destination route for this fee operation. | fees_revenue |
| Deductible from transaction? | When enabled, the fee is deducted from the transaction amount (recipient pays); when disabled, the fee is added on top (sender pays). | Off |
When Deductible from transaction? is enabled, Reference Amount is forced to
Original Amount (the After Fees Amount option is disabled in the form).Percentage Fee
A percentage of the Transaction amount.| Field | Description | Example |
|---|---|---|
| Percentage | Percentage rate applied to the reference amount. Must be greater than 0 and less than or equal to 100. | 2.5 |
| Fee Name | Unique identifier for this fee, used as the JSON object key. Must start with a letter or underscore and contain only letters, numbers, or _. | processingFee |
| Reference Amount | Original Amount to charge on the transaction value as sent, or After Fees Amount to charge on the value after previous fees in the package. | Original Amount |
| Credit Account ID | Alias of the account that receives the fee amount. | @fees_revenue |
| Route From | Optional. Name or UUID of the source route for this fee operation. | payments_in |
| Route To | Optional. Name or UUID of the destination route for this fee operation. | fees_revenue |
| Deductible from transaction? | Enable so the fee is deducted from the transaction amount; disable to add the fee on top of the transaction. | Disabled |
Max Between Types
Calculates a flat amount and a percentage, then applies the highest result. Both calculations are required.| Field | Description | Example |
|---|---|---|
| Flat Fee (Calculations) | First calculation row. Fixed amount candidate. Must be a positive number. | 1.00 |
| Percentage Fee (Calculations) | Second calculation row. Percentage candidate; must be greater than 0 and less than or equal to 100. | 2.0 |
| Fee Name | Unique identifier for this fee, used as the JSON object key. Must start with a letter or underscore and contain only letters, numbers, or _. | guaranteeFee |
| Reference Amount | Base used to calculate the percentage candidate before the comparison. | Original Amount |
| Credit Account | Alias of the account that receives the resulting (highest) fee amount. | @fees_guarantee |
| Route From | Optional. Name or UUID of the source route for this fee operation. | payments_in |
| Route To | Optional. Name or UUID of the destination route for this fee operation. | fees_revenue |
| Deductible from transaction? | When enabled, the higher of the two results is deducted from the transaction amount; when disabled, it is added on top. | Disabled |
The Max Between Types form always requires exactly two calculations: one of type
Flat Fee and one of type Percentage Fee. The Console computes both and applies the highest.Important notes
Fee priority ordering
When a package contains multiple fees, they are applied in priority order (lowest number first). This matters when usingAfter Fees Amount as a reference, since earlier fees affect the calculation base for later fees.
Example:
- Fee A (Priority 1): 1% on original amount
- Fee B (Priority 2): 0.5% on after fees amount
- Fee A = $1.00 (1% of $100)
- Fee B = $0.495 (0.5% of $99)
Amount range considerations
- Ranges should not overlap between packages for the same transaction route
- Use
0.01as minimum for packages that should apply to all transactions - Use a high maximum (e.g.,
999999999.99) for no upper limit - Transactions exactly at min or max values are included in the range
Waived accounts behavior
- Waived accounts bypass all fees in the package, not just specific fees
- Use account aliases (not IDs) when adding waived accounts
- Waivers apply when the waived account is the source of the transaction
What to do next
After creating the Fee Package, run a test calculation in Running a Fee Estimation before using it with live Transactions.