Overview
Fees Engine is built to give you complete control over how fees are applied, calculated, and tracked across industries like finance, logistics, agribusiness, healthcare, and beyond. It brings transparency, automation, and precision to every fee-related transaction, storing them in dedicated client ledgers to ensure accountability and traceability at every step.
Test the Fee Engine Plugin locallyRun Lerian’s plugins without deploying to Kubernetes using our plugins-docker-compose repository.
Keep in mind that these services require a valid license to run. Without it, the application will not start. For license details, check our License documentation.
Why use Fees Engine?
The Fees Engine plugin helps you easily manage complex fee logic. Whether you're applying a flat rate, distributing fees proportionally, or simulating transactions in advance, this plugin is built for flexibility and scale.
Here’s what it unlocks:
- Flexible fee configuration via fee packages—tailored to account groups or specific ledgers.
- Multiple calculation methods: flat fees, percentual rates, and “max between types” logic.
- Proportional fee distribution for marketplace flows and multi-account operations.
- Support for accounting routes via
transactionRoute
,routeFrom
, androuteTo
. - Simulation tools to preview calculations before executing transactions.
- Fee exemption logic by account and transaction value ranges.
- Priority-based application to control the order in which multiple fees are applied.
- Accurate deduction mechanics with
isDeductibleFrom
support.
TipFees Engine is a separate plugin. If you'd like to learn more or evaluate it for your use case, get in touch with our team.
What are fees?
Fees are monetary values charged in exchange for services, products, or access to resources. Their purpose depends on the industry, but the need for clarity and consistency is universal. Below are just a few examples:
Finance
In the financial sector, fees are applied to cover operational costs and ensure legal compliance.
- Account maintenance fee: Keeps accounts operational and covers administrative costs.
- Transfer fee: Charged for transactions like TEDs or international transfers.
Logistics and transportation
In the logistics sector, fees are related to the use of transportation and storage services.
- Handling fee: Applied during storage and physical movement of goods.
- Unloading fee: Covers unloading operations at delivery points.
Pharmaceutical and healthcare
In the pharmaceutical sector, fees aim to ensure the quality and regulation of services.
- Medication registration fee: Related to regulatory approvals and market entry.
- Laboratory analysis fee: Covers testing and quality control costs.
Agricultural
In the agricultural sector, fees are linked to commercialization and regulatory processes.
- Sanitary inspection fee: Ensures health compliance for agricultural exports.
- Agricultural export fee: Covers admin and regulatory export costs..
Fee Packages
A Fee Package defines how fees are applied to a transaction. It groups one or more fee rules and can be customized by segment, ledger, and accounting routes.
You can create different packages for different products, transaction types, or customer segments, each with its own calculation logic, route configuration, and priority rules.
A package typically includes:
- transactionRoute – The main accounting route for the transaction.
- segmentId – The product or segment the package applies to.
- ledgerId – The ledger that records the transaction and its fees.
- waivedAccounts – Accounts that should be exempt from fees.
- fees – A map of individual fee rules, each including:
- priority – Defines execution order.
- routeFrom and routeTo – Custom accounting routes for the fee.
- isDeductibleFrom – Whether the fee is deducted from the original amount.
- referenceAmount – The base amount used for calculations.
NoteFees Engine requires explicit route configuration for each fee and direction (e.g., debit or credit).
Validation rules
To ensure consistency and prevent configuration errors, Fees Engine enforces the following rules:
- Fee priority must be unique within a package.
- Fees with
isDeductibleFrom: true
must usereferenceAmount: originalAmount
. - Fees with priority 1 must also use
referenceAmount: originalAmount
. - Fields like
organizationId
,ledgerId
, andcreditAccount
must exist in Midaz and are validated using the Retrieve an Account by Alias endpoint.
ImportantFees Engine validates all packages and transactions according to the latest Midaz standards. Make sure your configuration complies with required rules for fields like
ledgerId
,segmentId
,creditAccount
, andreferenceAmount
.
Choosing the right endpoint: calculate vs. simulate
Fees Engine provides two endpoints to apply fees. They behave differently, depending on how much control and flexibility you need:
- Automatically fetches all available packages for the given organization and ledger.
- Picks the best match based on transaction context.
- Applies the corresponding fee rules.
- If no matching package is found, no fees are applied.
- Simulates fees for a specific package using its
packageId
. - Returns calculated fees only if the transaction matches the package’s conditions.
- Useful for testing, debugging, or giving users a preview of fees, without writing to the ledger.
NoteUse
calculate
when you want the engine to decide which package to apply. Usesimulate
when you want full control over which package to test.
Routing fees
Every fee can have:
- A
routeFrom
, which represents the accounting route for the debit (or source). - A
routeTo
, which represents the accounting route for the credit (or destination). - A
transactionRoute
, which represents the overall nature of the transaction.
This allows granular tracking of each fee entry in the ledger.
Deductible fees
If a fee is flagged as deductible ( isDeductibleFrom: true
), the following logic applies:
- The full value is sent from the source account.
- The fee is subtracted from the destination account’s received value.
- The
referenceAmount
used in calculations must beoriginalAmount
.
This approach ensures the sender sends the full amount, and the deduction is applied only at the receiving end.
Soft delete for safe recordkeeping
No data gets lost. When a resource is deleted:
- It’s marked with a
deletedAt
timestamp. - It's excluded from standard queries, but still stored in the database for audit and historical accuracy.
This ensures full traceability if needed.
Integrations
You can use Fees Engine on its own or alongside other components in your stack. It integrates seamlessly with Lerian plugins or your own implementation to apply fees based on your unique business logic.
Popular use cases include:
- Exchange engines.
- Lending platforms.
- Bill payment systems.
- Smart contracts.
- Pix (Brazil’s instant payment platform).
Security recommendations
Security is foundational when working with Lerian plugins. Before deploying any plugin into your environment, we strongly recommend reviewing the Security recommendations.
Whether you're working with Access Manager, Fees Engine, CRM, or Smart Templates, each plugin should be implemented in alignment with security best practices, including securing network boundaries, managing secrets, applying patch management, and enforcing strict access controls.
By following these guidelines, you help ensure every plugin runs securely, integrates smoothly with your infrastructure, and maintains compliance, data integrity, and user trust.
Updated about 3 hours ago