Creating a Fee Package

Build a new Fee Package in the Midaz Module by configuring basic info, amount ranges, flat or percentage fee rules, waivers, and priorities from the Console UI.

A Fee Package groups fee rules and defines when they apply to Transactions.

Before you start

---

• Enable the Fees Engine 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

---

1. Go to the Fee Packages page and click the New Package button.

2. The New Fee Package form will open with multiple sections to configure.

   Check the field guide for more information about the fields in the form.

If successful, the Console shows a confirmation message and opens the Fee Packages list.

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
Segment	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 priority 1 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 you enable Deductible from transaction?, the form forces Reference Amount to Original Amount and disables the After Fees Amount option.

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. The form requires both calculations.

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.

Account Waivers

Field	Description	Example
Account Alias	The alias of the account that will be waived.	@customer_john_checking

Important notes

---

Fee priority ordering

When a package contains multiple fees, the Console applies them in priority order (lowest number first). This matters when using After 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

On a $100 transaction:

• 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.01 as minimum for packages that should apply to all transactions
• Use a high maximum (e.g., 999999999.99) for no upper limit
• The range includes Transactions exactly at the min or max values

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.

API equivalent

Create Package endpoint