Skip to main content
Fees Engine gives you powerful control over how fees are calculated, applied, and tracked. But with that flexibility comes the need for careful configuration and operational discipline — especially in production environments where accuracy and auditability are non-negotiable. These recommendations complement the Fees Engine overview and the calculation mechanics guide.

​
1. Design fee packages with clear naming and segmentation

Fee packages are the foundation of your fee logic. A well-organized package structure makes it easier to maintain, debug, and audit your fee configuration over time.
  • Use descriptive names that reflect the business context (e.g., “pix-transfer-standard”, “wire-premium-segment”).
  • Segment by product and customer group using segmentId. This allows you to apply different fee rules to different customer tiers without creating conflicting packages.
  • Keep packages focused. A package that tries to cover too many scenarios becomes hard to test and maintain. Prefer multiple focused packages over one that does everything.
  • Document your package structure internally. As your package count grows, a clear reference of which package applies where prevents misconfiguration.

​
2. Set fee priorities carefully

When a package contains multiple fees, the priority field determines the order of execution. Getting this wrong can produce incorrect calculations.
  • Priority 1 must always use referenceAmount: originalAmount. This is enforced by the engine.
  • Fees with isDeductibleFrom: true must also use referenceAmount: originalAmount. This ensures deductible fees are always calculated against the full transaction value.
  • Priority must be unique within a package. Duplicate priorities will be rejected.
  • Think about fee dependencies. If one fee adjusts the transaction value and another fee should be calculated on the adjusted value, use referenceAmount: afterFeesAmount with a higher priority number. If the second fee should reference the original value, use originalAmount.
When in doubt, start with a simple configuration (one or two fees per package) and validate the results using the simulate endpoint before adding complexity.

​
3. Always simulate before applying fees in production

Fees Engine provides a simulate endpoint that lets you preview fee calculations without writing anything to the ledger. Use simulation to:
  • Validate new packages before activating them. Confirm that the calculated values match your expected results across different transaction amounts.
  • Test edge cases: zero-amount transactions, boundary values at minimumAmount and maximumAmount thresholds, and exempted accounts.
  • Preview fees for users. If your product shows fees before confirmation, use the simulate endpoint to provide accurate previews.
  • Debug unexpected results. If a calculated fee doesn’t match expectations, simulate the same transaction with a specific packageId to isolate the issue.
The calculate endpoint automatically selects the best matching package. The simulate endpoint requires a specific packageId, giving you full control over which package to test.

​
4. Manage exemptions explicitly

Fees Engine supports two types of exemptions: by transaction amount range and by account.
  • Amount ranges (minimumAmount, maximumAmount): Define the transaction value window in which fees apply. Transactions outside this range are exempt. Use this for promotional thresholds or tiered pricing.
  • Waived accounts (waivedAccounts): Specific accounts exempt from fees within a package. Use this for internal accounts, employee accounts, or partnership arrangements.
Best practices for exemptions:
  • Keep waived account lists short and reviewed. Large lists become hard to audit. Periodically review which accounts are exempted and why.
  • Document the business reason for each exemption in your internal records.
  • Test exemption boundaries. If your range is R0–300,makesuretransactionsatexactlyR 0–300, make sure transactions at exactly R 300 and R$ 301 behave as expected.

​
5. Enable and tune caching for performance

Fees Engine caches fee packages in memory to reduce database queries during high traffic. Configure caching through environment variables: 
fees:
  configmap:
    PACKAGE_CACHE_ENABLED: "true"
    PACKAGE_CACHE_TTL_SECONDS: "600"
  • PACKAGE_CACHE_ENABLED (default: true): Enables or disables the package cache.
  • PACKAGE_CACHE_TTL_SECONDS (default: 600): Time-to-live in seconds before cached packages are refreshed from the database.
Recommendations:
  • Keep caching enabled in production. It significantly reduces latency for high-volume transaction processing.
  • Adjust TTL based on your change frequency. If you update packages frequently, use a shorter TTL (e.g., 60–120 seconds). If packages are stable, the default 600 seconds is appropriate.
  • Be aware of cache delay. After updating a package, the change may take up to the configured TTL to propagate. If you need immediate effect, restart the service or temporarily reduce the TTL.

​
6. Use correct numeric values

All financial values in Fees Engine must be expressed as strings using the numeric type. This prevents floating-point precision errors that are common with decimal arithmetic. 
"value": "12.50"
  • Always send values as strings, even whole numbers (e.g., "100" not 100).
  • Never use floating-point types for monetary calculations in your integration layer.
  • Be aware that fee splits involving repeating decimals (e.g., dividing R$ 10 by 3 accounts) are automatically adjusted by the engine to keep ledger totals exact.
Fees Engine requires Midaz v3.x.x or later. The v2.x.x amount + scale format is not compatible. Upgrade Midaz before deploying Fees Engine.

​
7. Use soft delete for auditability

When you delete a fee package, Fees Engine marks it with a deletedAt timestamp rather than removing it from the database. This preserves the audit trail for historical transactions that referenced that package.
  • Don’t rely on hard deletion for fee packages in production. Historical transactions may reference deleted packages for reconciliation.
  • Periodically review deleted packages if your database grows significantly. Archiving strategies can help manage storage without losing audit capability.

​
8. Monitor the Fees Engine in production

Fees Engine supports OpenTelemetry for traces and metrics. Enable it to gain visibility into fee calculation performance and behavior. 
fees:
  configmap:
    ENABLE_TELEMETRY: "true"
    OTEL_RESOURCE_SERVICE_NAME: "plugin-fees"
In production:
  • Monitor health endpoints. Fees Engine exposes /health for readiness and liveness checks (default port: 4002).
  • Set up alerts for sustained high latency on fee calculations, which may indicate database contention or cache misconfiguration.
  • Monitor MongoDB connection pool usage, disk space, and replication health. The default MONGO_MAX_POOL_SIZE is 1000.
  • Review pod resource usage. Default limits are 200m CPU / 256Mi memory. Adjust based on your traffic patterns and autoscaling behavior.

​
9. Keep versions compatible

Before upgrading Fees Engine:
  • Check the version compatibility table to confirm compatibility with your Midaz Core version.
  • Always upgrade Midaz Core first, then Fees Engine.
  • Back up your MongoDB data and Helm values before any major upgrade.
  • Test the upgrade in a staging environment before applying it to production.
For upgrade procedures, see the Helm upgrade guide.

​
10. Review the security recommendations

Fees Engine processes financial data and integrates with Midaz ledger operations. Make sure your deployment follows the platform-wide Security recommendations, which cover:
  • Network segmentation and Zero Trust Architecture
  • Secret management and rotation (including LICENSE_KEY and database credentials)
  • TLS 1.2+ enforcement for all communications
  • RBAC configuration via Access Manager
  • Patch management and vulnerability scanning