The Fees Engine simplifies fee management, ensuring that transactions are processed smoothly, accurately, and in line with your business rules.

Whether you're applying fees in production or simulating them in advance, Fees Engine offers full control and flexibility. This guide walks you through the full lifecycle, from creating packages to reviewing fee results.

👍

Tip

Not sure whether to calculate or simulate? We'll show you how to choose between the two based on your use case.

Typical usage

---

Here's how the process works, from configuring fees to seeing the results.

Step 1 - Create your fee packages

Start by setting up fee packages that define how fees are applied. To do so, use the Create a Package endpoint. Each package contains a set of fee rules and matching criteria.

You can tailor packages to different segments or ledgers using:

• transactionRoute – Identifies the nature of the transaction.
• segmentId – Groups customers or product types.
• ledgerId – Defines which ledger records the transaction.
• Minimum and maximum amount – Optional thresholds for fee application.
• routeFrom / routeTo – Define how each fee moves across accounting flows.

This flexibility lets you apply distinct fees per scenario, from account-based setups to value-based.

Managing Packages

The following endpoints are also available for you to manage the packages:

• List Packages - List all packages created.
• Retrieve a Package - Retrieve information of a specific package.
• Update a Package - Update the information of a specific package.
• Delete a Package - Soft-delete a package.

(optional) Step 2 - Run a simulation

If you want to preview how a fee package would behave before committing a real transaction, use the Simulate Transaction Fees endpoint.

This simulation helps validate:

• Which fee rules will be triggered.
• How the package will behave with the given values.
• Whether any exemptions apply.

Step 3 - Create a transaction

Once packages are set, trigger the actual transaction using the create a transaction endpoint. Include the appropriate transactionRoute, segmentId, and ledgerId so the engine can evaluate the matching package.

Step 4 - The Fees Engine kicks in

Fees Engine automatically sends a call to the Calculate Fees for a Package endpoint and evaluates whether a package applies based on:

• transactionRoute
• segmentId
• ledgerId
• Minimum and maximum amount
• waivedAccounts (for fee exemptions)

📘

Note

Only one package is selected per transaction.

Step 5 - Check for exemptions

The system checks:

• If the transaction amount is outside the allowed range.
• If the source account is exempt

If either condition is met, no fees are applied and the transaction proceeds normally.

Step 6 - Fee calculation and application

If a package is applied, Fee Engines:

• Calculates fee values based on the selected applicationRule.
• Applies fees proportionally across accounts if needed.
• Uses isDeductibleFrom to define if the fee is added or deducted.
• Routes fees to the correct creditAccount using the configured routeFrom and routeTo.
• Returns the full transaction result along with the packageAppliedID in the metadata.

Step 7 - Ledger updates

Once fees are calculated, the Transactions component takes over. It processes:

• Debits from source accounts
• Credits to fee destinations
• Fee breakdown per route and account

Every movement is stored in the ledger for full traceability and auditability.

Step 8 - Review and confirm

After execution, you can:

• Inspect the final transaction and amounts per account.
• Confirm the fee package that was applied.
• Verify all fee movements via metadata and ledger records.

Why simulate a transaction?

---

Simulations let you preview how a specific fee package behaves, without running a real transaction or writing to the ledger.

Use simulations when:

• You want to test a specific package.
• You’re debugging fee rules or thresholds.
• You want to validate exemptions, value ranges, or proportional splits.
• You need a preview before creating a real transaction.
• You're building an interface and want to show estimated fees

Fee Engines provides the Simulate Transaction Fees endpoint for this purpose.

Unlike Calculate Fees for a Package, which searches for the best-matching package, the simulation endpoint requires you to pass a packageId and returns what would happen if that exact package were applied.

What do you get with a simulation?

• A full simulation of the fee rules.
• Which accounts would be charged.
• How the fee would be split.
• No impact on the ledger.

👍

Tip

Use simulations when you're not ready to commit the transaction, or want to give your users a clear fee preview.

Common errors

---

Fees Engine validates every request to ensure consistency and correct fee logic. Below are the most frequent issues you might run into when creating packages or processing transactions.

📘

Note

Want the full list of error codes? You’ll find it in the Fees Engine error list page in the API reference.