What is Fees Engine?

Fees is an embedded component of the unified Midaz ledger process. It provides fee and billing configuration and calculations alongside the ledger. Deploy and configure it with Midaz; it is not a separate service or plugin.

​

Why use Fees Engine?

---

The Fees Engine helps you manage complex fee logic. It applies flat rates, distributes fees proportionally, and estimates transactions before you run them. 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.
• Estimation tools to preview calculations before executing transactions.
• Fee exemption logic by account and transaction value ranges.
• Priority-based application to control the order of multiple fees.
• Accurate deduction mechanics with isDeductibleFrom support.
• Volume-based billing via billing packages — charge based on accumulated transaction counts per period (daily or monthly).
• Maintenance billing for recurring per-account charges, targeting accounts by segment, portfolio, or explicit list.
• Free quotas and progressive discounts to model tiered pricing and volume incentives.
• Segment-based exemptions to exempt entire account groups from fee packages without listing individual accounts.

​

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 cover operational costs and support legal compliance.

• Account maintenance fee: Keeps accounts operational and covers administrative costs.
• Transfer fee: Applies to transactions like TEDs or international transfers.

​

Logistics and transportation

In the logistics sector, fees cover transportation and storage services.

• Handling fee: Applies during storage and physical movement of goods.
• Unloading fee: Covers unloading operations at delivery points.

​

Pharmaceutical and healthcare

In the pharmaceutical sector, fees 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 cover commercialization and regulatory processes.

• Sanitary inspection fee: Ensures health compliance for agricultural exports.
• Agricultural export fee: Covers admin and regulatory export costs.

​

Scope

---

Fees and Billing support organization scope and ledger scope in parallel. On the ledger-scoped v2 surface, the ledger named by the request is authoritative: a ledgerId query parameter is not accepted, and a body ledgerId must match the ledger in the request. A package owned by another ledger is returned as not found.

​

Fee Packages

---

A Fee Package defines how the engine applies fees to a transaction. It groups one or more fee rules. You customize it by segment, ledger, and accounting routes. You can create different packages for different products, transaction types, or customer segments. Each package has its own calculation logic, route configuration, and priority rules. A package includes required fields and can add optional matching or exemption fields:

• ledgerId – The ledger that records the transaction and its fees.
• transactionRoute – The main accounting route for the transaction, for route-level matching.
• segmentId – The product or segment the package applies to, for segment-level matching.
• waivedAccounts – Accounts to exempt from fees, when you configure exemptions.
• 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 engine deducts the fee from the original amount.
  • referenceAmount – The base amount for calculations.

​

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 use referenceAmount: originalAmount.
• Fees with priority 1 must also use referenceAmount: originalAmount.
• Fields like organizationId, ledgerId, and creditAccount must exist in Midaz. Fees Engine validates them with the Retrieve an Account by Alias endpoint.

​

Choosing the right endpoint: calculate vs. estimate

Fees Engine provides two endpoints to apply fees. They behave differently based on the control 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 package matches, the engine applies no fees.

​

Estimate transaction fees

• Estimates fees for a specific package by its packageId.
• Returns calculated fees only if the transaction matches the package’s conditions.
• Useful for testing, debugging, or a preview of fees, without writing to the ledger.

​

Segment-based exemptions

Fee packages support exempting individual accounts by listing their aliases in waivedAccounts. To exempt a whole group at once, add a segment reference to that same list using the segment:<segment-uuid> form — for example "segment:seg_premium_01HZ...". Use segment-based exemptions when:

• A customer tier (such as premium accounts) is universally exempt from a fee.
• Internal or partner accounts belong to an existing segment in Midaz.
• Maintaining a list of individual account aliases is impractical at scale.

​

Billing Packages

---

Billing Packages calculate charges from accumulated transaction volume over a period — daily or monthly. Fee packages charge per individual transaction. Billing packages count the qualifying transactions and return payloads for your orchestrator to execute. Two types are available:

• Volume — charges based on the number of transactions matching an event filter in the period.
• Maintenance — charges a fixed recurring fee per active account, once per billing period.

​

Volume packages

A volume package counts transactions that match a given eventFilter (transaction route + status) within the billing period. It then applies a charge from the configured pricing model. Key fields:

• eventFilter — Specifies which transactions to count: transactionRoute and status.
• pricingModel — Either tiered (unit price varies by quantity range) or fixed (single unit price regardless of volume).
• tiers — Quantity ranges (minQuantity, maxQuantity) and unitPrice per unit within each range.
• freeQuota — Number of transactions exempt per period. The engine subtracts this count before it applies pricing.
• discountTiers — Progressive discounts: when total volume meets a threshold, the engine applies the configured discount percentage to the final amount.
• countMode — Accepts perRoute or perAccount. Volume calculation counts all matching transactions on the route as a single total.
• debitAccountAlias / creditAccountAlias — Accounting routes for the charge.

​

Maintenance packages

A maintenance package applies a fixed fee per active account in the billing period, regardless of transaction activity. Key fields:

• feeAmount — Fixed charge per active account.
• assetCode — Currency for the charge.
• maintenanceCreditAccount — Account that receives the fee revenue.
• accountTarget — Defines which accounts to charge. Use exactly one per package:
  • segmentId — All accounts in the segment.
  • portfolioId — All accounts in the portfolio.
  • aliases — Explicit list of account aliases (maximum 100 accounts).

​

Managing billing packages

The following endpoints manage billing packages:

• POST /v1/billing-packages — Create a billing package.
• GET /v1/billing-packages — List all billing packages.
• GET /v1/billing-packages/:id — Retrieve a specific billing package.
• PATCH /v1/billing-packages/:id — Update a billing package (label, description, enable).
• DELETE /v1/billing-packages/:id — Soft-delete a billing package.
• POST /v1/billing/calculate — Calculate billing for a period.

​

Fee Packages vs. Billing Packages

---

​

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 you flag a fee as deductible ( isDeductibleFrom: true), the following logic applies:

• The source account sends the full value.
• The engine subtracts the fee from the amount the destination account receives.
• The referenceAmount for calculations must be originalAmount.

This way, the sender sends the full amount, and the destination account absorbs the deduction.

​

Soft delete for safe recordkeeping

---

Fees Engine loses no data. When you delete a resource:

• Fees Engine marks it with a deletedAt timestamp. Active records return deletedAt: null.
• Standard queries exclude it, but the database still stores it for audit and history.

This keeps full traceability when you need it.

​

Integrations

---

You can use Fees Engine on its own or alongside other components in your stack. It works with Lerian plugins or your own implementation to apply fees from your 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 you work with Lerian products and plugins.
Before you deploy any component, review our Security Recommendations. Implement each product and its plugins in line with security best practices, such as:

• Securing network boundaries
• Managing and rotating secrets
• Applying timely patch management
• Enforcing strict role-based access controls (RBAC)

These practices keep Lerian’s products and plugins secure and compliant across your stack.

​

Next steps

---