Using Fees Engine

Whether you’re applying per-transaction fees or calculating periodic billing charges, Fees Engine offers full control and flexibility. This guide walks you through both workflows: fee packages (per-transaction) and billing packages (per-period).

Not sure which to use? Fee packages apply charges at transaction time. Billing packages calculate charges over a period (daily or monthly) for your orchestrator to execute. You can use both simultaneously.

Fee packages: per-transaction workflow

Fee packages apply charges synchronously when a transaction is created. 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 ledgers, segments, and transaction routes using:

transactionRoute - Identifies the nature of the transaction, when route-level matching is needed.
segmentId - Groups customers or product types, when segment-level matching is needed.
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 an estimation

If you want to preview how a fee package would behave before committing a real transaction, use the Estimate Transaction Fees endpoint. This estimation 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 ledgerId and any configured matching fields, such as transactionRoute or segmentId, so the engine can evaluate the right 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, when configured
segmentId, when configured
ledgerId
Minimum and maximum amount
waivedAccounts, when configured for fee exemptions

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 estimate a transaction?

Estimations let you preview how a specific fee package behaves, without running a real transaction or writing to the ledger. Use estimations 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 Estimate Transaction Fees endpoint for this purpose. You only have to pass a packageId and the endpoint returns what would happen if that exact package were applied.

What do you get with an estimation?

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

Use estimations 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.

Code	Title	Message
FEE-0002	Missing fields in request	Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.
FEE-0012	Entity not found	No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.
FEE-0013	Invalid fee priority	The priority field in fees is invalid. Field can not be repeated.
FEE-0015	minimumAmount greater than maximumAmount	minimumAmount value is greater than maximumAmount.
FEE-0022	Failed to calculate fee	Error to make the calculation of a fee about a transaction.
FEE-0024	originalAmount is required when priority is one	For Priority equals to one, referenceAmount must be ‘originalAmount’ for fee.
FEE-0025	Failed to apply rule: flatFee or percentual	applicationRule flatFee or percentual must have exactly 1 calculation for Fee.
FEE-0035	Package amount range overlap	The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.

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

Billing packages: per-period workflow

Billing packages calculate charges based on accumulated transaction volume or per-account maintenance over a billing period. Unlike fee packages, billing is caller-triggered — your orchestrator decides when to calculate and executes the resulting charges.

Step 1 — Create billing packages

Set up billing packages that define your periodic charge rules. Each package is either volume or maintenance type. Volume package example — charge per Pix sent with tiered pricing:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "Pix Send Monthly Billing",
  "description": "Monthly volume billing for Pix transactions",
  "ledgerId": "ldg_01HZ...",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 100, "unitPrice": "0.50" },
    { "minQuantity": 101, "maxQuantity": 500, "unitPrice": "0.35" },
    { "minQuantity": 501, "maxQuantity": null, "unitPrice": "0.20" }
  ],
  "freeQuota": 10,
  "discountTiers": [
    { "minQuantity": 200, "discountPercentage": "5.00" },
    { "minQuantity": 400, "discountPercentage": "10.00" }
  ],
  "countMode": "perAccount",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-revenue"
}

Maintenance package example — monthly fee per active PF account:

POST /v1/billing-packages
Headers:
  X-Organization-Id: org_01HZ...

Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active PF accounts",
  "ledgerId": "ldg_01HZ...",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "seg_pf_01HZ..."
  }
}

Step 2 — Trigger billing calculation

Call POST /v1/billing/calculate with the ledger ID and billing period. The engine evaluates all active billing packages matching the criteria.

POST /v1/billing/calculate

Body:
{
  "ledgerId": "ldg_01HZ...",
  "period": "2026-03",
  "type": "volume"
}

The period field supports three formats: YYYY-MM (monthly), YYYY-Www (weekly, e.g., 2026-W13), and YYYY-MM-DD (daily). The type field is optional. Use "volume" or "maintenance" to restrict the calculation to one type. Omit it to calculate both types in a single call.

Step 3 — Receive calculation results

The engine returns an array of results, each containing a transactionPayload ready to be sent to Midaz. Each result includes:

The billing package that generated it.
The calculated amounts with full breakdown (tiers applied, discounts, free quota subtracted).
A transaction payload with source.from (debit entries) and distribute.to (credit entries).
Structured audit metadata for traceability.

Step 4 — Execute charges

Send each transactionPayload to Midaz via POST /transactions/json to create the actual billing transactions. This step is your orchestrator’s responsibility — Flowker, a cron job, or any other system.

The billing engine calculates and returns results. It does not create transactions in Midaz. Your orchestrator controls when and how charges are executed.

Step 5 — Review and reconcile

After executing the charges:

Verify the created transactions in Midaz match the billing calculation results.
Use the audit metadata in each result for reconciliation.
The billing calculation is stateless — you can re-run it for the same period to verify results.

Managing billing packages

Use these endpoints to manage existing billing packages:

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 only).
DELETE /v1/billing-packages/:id — Soft-delete a billing package.

Billing calculation follows an all-or-nothing policy. If any package fails during calculation, the entire operation fails and no partial results are returned. Fix the failing package and re-execute.

Introduction

Fees Engine

Pix

Bank Transfer (TED)

Using Fees Engine

Fee packages: per-transaction workflow

Step 1 - Create your fee packages

(optional) Step 2 - Run an estimation

Step 3 - Create a transaction

Step 4 - The Fees Engine kicks in

Step 5 - Check for exemptions

Step 6 - Fee calculation and application

Step 7 - Ledger updates

Step 8 - Review and confirm

Why estimate a transaction?

What do you get with an estimation?

Common errors

Billing packages: per-period workflow

Step 1 — Create billing packages

Step 2 — Trigger billing calculation

Step 3 — Receive calculation results

Step 4 — Execute charges

Step 5 — Review and reconcile

Managing billing packages

Introduction

Fees Engine

Pix

Bank Transfer (TED)

Documentation Index

​Fee packages: per-transaction workflow

​Step 1 - Create your fee packages

​(optional) Step 2 - Run an estimation

​Step 3 - Create a transaction

​Step 4 - The Fees Engine kicks in

​Step 5 - Check for exemptions

​Step 6 - Fee calculation and application

​Step 7 - Ledger updates

​Step 8 - Review and confirm

​Why estimate a transaction?

​What do you get with an estimation?

​Common errors

​Billing packages: per-period workflow

​Step 1 — Create billing packages

​Step 2 — Trigger billing calculation

​Step 3 — Receive calculation results

​Step 4 — Execute charges

​Step 5 — Review and reconcile

​Managing billing packages

Fee packages: per-transaction workflow

Step 1 - Create your fee packages

(optional) Step 2 - Run an estimation

Step 3 - Create a transaction

Step 4 - The Fees Engine kicks in

Step 5 - Check for exemptions

Step 6 - Fee calculation and application

Step 7 - Ledger updates

Step 8 - Review and confirm

Why estimate a transaction?

What do you get with an estimation?

Common errors

Billing packages: per-period workflow

Step 1 — Create billing packages

Step 2 — Trigger billing calculation

Step 3 — Receive calculation results

Step 4 — Execute charges

Step 5 — Review and reconcile

Managing billing packages