Skip to main content
A reliable Midaz implementation depends on a few structural choices you make early. Avoid the common mistakes below to keep balances accurate and access under control.

​
Poor Ledger structuring

  • Mistake: You design ledgers that are too complex or too simplistic. For example, one ledger per customer creates fragmentation. Grouping unrelated processes creates confusion.
  • Best practice: Structure ledgers around key business areas or legal entities. Use organized groupings instead of a one-to-one approach. This improves manageability and internal transfers.

​
Not using Portfolios for clients

  • Mistake: You treat each account in isolation instead of grouping it under a portfolio. This makes it hard to track all accounts linked to a single customer.
  • Best practice: Create a portfolio for each customer. Group their accounts for simple queries, relationship management, and reporting.

​
Mixing Assets in one Account

  • Mistake: You manage multiple currencies or asset types in a single account, often through metadata overrides. This leads to unclear balances and reporting inconsistencies.
  • Best practice: Assign one asset per account. If a customer needs multi-currency support, create separate accounts. Use naming conventions or portfolios to structure them.

​
Inadequate Accounting Routes

  • Mistake: You submit transactions without properly configured Operation Routes or Accounting Routes (Transaction Routes in the API). This causes inconsistent validations, misrouted funds, and unreliable ledger data.
  • Best practice: Define Accounting Routes that reflect your business logic and compliance requirements, then set the Ledger setting accounting.validateRoutes to true to enforce them. Its default is false. Use Operation Routes to validate the source and destination of each operation when route validation is enabled. Structured routes keep every transaction auditable.

​
Overlooking External Account handling

  • Mistake: You mishandle external transactions. For example, you delete an account when funds leave the bank, which causes imbalances.
  • Best practice: Use the canonical @external/<asset-code> Account (for example, @external/BRL) for money that flows into and out of Midaz. This keeps the ledger balanced and matches real bank statements.

​
Security lapses in access control

  • Mistake: You grant excessive privileges to administrators or use shared accounts. This compromises security and accountability.
  • Best practice: Implement role-based access control (RBAC) from the start. Do not use root or admin accounts for daily operations. Enforce strict credential management. Audit permissions regularly to prevent unauthorized privilege escalation.

​
Improper error handling in transactions

  • Mistake: You fail to handle failed transactions in the integration layer. This leads to false assumptions about successful operations.
  • Best practice: Always validate transaction API responses. Implement retry mechanisms with backoff for transient errors. Log permanent failures. Make sure upstream systems, such as core banking applications, handle rejected transactions and notify the user.

​
Ensuring a robust Midaz implementation

Address these pitfalls early and Midaz stays a reliable financial backbone. Your team spends time on new features, not on avoidable problems.