Guides
Start typing to search…

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.


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, and routeTo.
  • 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.
👍

Tip

Fees 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.
📘

Note

Fees 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 withisDeductibleFrom: true must use referenceAmount: originalAmount.
  • Fees with priority 1 must also use referenceAmount: originalAmount.
  • Fields like organizationId, ledgerId, and creditAccount must exist in Midaz and are validated using the Retrieve an Account by Alias endpoint.
❗️

Important

Fees 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, and referenceAmount.


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:

Calculate fees for a package

  • 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.

Simulate transaction fees

  • 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.
📘

Note

Use calculate when you want the engine to decide which package to apply. Use simulate 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 be originalAmount.

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 3 days ago