Recommended workflow

Follow the recommended Midaz onboarding workflow to create your Organization, Ledgers, Assets, Account Types, and Accounts in the correct order, step by step.

You have explored how Midaz works, from its core entities to its architecture and security. This page turns that knowledge into a working setup.

A structured workflow keeps every transaction clear, traceable, and auditable from the start. Follow the steps below in order. They set up your Organization, Ledgers, Assets, Account Types, and Accounts.

Setting up and managing Ledgers

---

When you onboard to Midaz, follow these steps to build a solid base for your financial infrastructure:

Figure 1. Workflow for setting up and managing ledgers.

Step 1: Set up the Organization

Your organization in Midaz represents your bank or business entity. If you have not created it yet, set it up in the Console or API. Make sure the core details are accurate, such as the legal name and identifiers. This context underpins all ledger operations.

Step 2: Create the Ledgers

Create a Ledger under your organization to hold financial records. Most setups start with a primary ledger for all customer-facing operations (for example, “Main Banking Ledger”). At first it contains no accounts. It serves as the base layer for all financial activity.

Step 3: Define Asset types

Register the assets your ledger supports. These can include currencies (for example, BRL, USD), points, or crypto tokens. You use these assets across your account and transaction configuration. You can add more assets as your product portfolio grows.

Step 4: Create Account Types

To enforce account classification rules, define your Account Types. These are structured categories, for example user_wallet, treasury, or revenue. You reference them later during account creation or transaction validation.

When you enable Account Type validation, each new account must use a registered Account Type. By default, Account Types are optional. This keeps classification consistent across your ledger.

Each Account Type has a keyValue. The keyValue must be unique and alphanumeric, with dashes and underscores allowed. You use these identifiers in validation flows and transaction routes.

Step 5: Configure Accounting Routes

Use Operation Routes and the Transaction Route (the transactionRoute resource in the API) to define and enforce validation for your transactions.

• First, create the Operation Routes. Each Operation Route validates one leg of the transaction. For example, the debit must come from an account of type user_wallet, and the credit must go to the alias @external/BRL.
• Then, create the Transaction Route. It combines the individual operation routes into a complete flow. An example is a cashout transaction with specific debit and credit validations.

After you configure routing and enable validation on the ledger, all transactions must match the defined routing structure. Midaz rejects any transaction that does not match.

The route field in the transaction payload must include the ID of the Transaction Route you created.

Step 6: Manage your Ledgers

Keep your ledgers clean and scalable with the following best practices:

• Use Midaz’s RBAC system to assign permissions and control access per ledger.
• Plan separate ledgers when needed, for example “Testing”, “Internal”, or “Multi-entity”. Document their ownership.
• Review and reconcile ledger data regularly, especially when you integrate with external settlement systems.
• Midaz enforces double-entry logic, so every movement is fully traceable. Do not change balances manually.

Configuring Accounts, Portfolios, and Segments

---

This section shows how to structure customer data and product entitlements in Midaz.

Figure 2. Workflow for configuring Accounts, Portfolios, and Segments.

Step 1: Create a customer Portfolio

Create a Portfolio for each new customer. Portfolios act as the logical containers for accounts. Link each portfolio to your CRM or internal system through metadata (for example, an Entity ID).

Step 2: Set up customer Accounts

Each financial product or asset the customer holds becomes a separate Account under their portfolio.

• A checking account in BRL and a savings account in USD are separate accounts.
• If you enable Account Types, the type field must match one of the pre-registered values.
• Use account aliases to simplify downstream operations.

Account Types standardize account categorization across your ecosystem. They improve routing, reporting, and integrations.

Step 3: Apply segmentation

Use Segments to categorize portfolios or accounts (for example, standard, vip, enterprise). These tags drive dynamic logic based on customer segmentation, such as fee exemptions or tiered interest.

Step 4: Establish sub-accounts (optional)

For organizations or special cases, you can configure sub-accounts. Use clear naming conventions to keep traceability (for example, “Acme USD - Payroll”).

Step 5: Set the initial balance

Use the Transactions API to add the opening balance. This keeps traceability and double-entry compliance:

• Debit the funding source.
• Credit the new account.
• Do not update balances manually. Midaz tracks every value through transactions.

Step 6: Verify and review

Before you run operations, check the following:

• Confirm each account has the correct assets and types.
• Validate account balances.
• Check that you applied segmentation.
• Confirm the setup in the API or the Console.

Step 7: Ongoing Account management

Manage lifecycle operations through the API or Console to keep system integrity:

• Update account details as needed.
• Close accounts only once the balance reaches zero.
• Reclassify portfolios/accounts if segmentation changes.

Implementing double-entry transaction management

---

Midaz guarantees ledger integrity through strict enforcement of double-entry logic. Every transaction must contain at least one debit and one credit operation.

Figure 3. Workflow for implementing double-entry transaction management

Step 1: Structure the transaction

Structure your Transaction object:

• After you configure your Transaction Route, insert its ID into the route field of your transaction payload.
• Define the source and destination accounts, with their asset and value details.
• Add descriptive metadata to keep traceability and clarity.

Step 2: Choose your integration method

Use the Transactions API for programmatic transaction creation.

Step 3: Enforce double-entry validation

Midaz checks that the sum of credits matches the sum of debits. Midaz rejects a transaction that has a mismatch or a structural violation.

Step 4: Implement idempotency

Use idempotency keys to prevent duplicates from network retries. Midaz recognizes a repeated key and replays the original response instead of processing the request twice.

Step 5: Track and reconcile transactions

Use built-in tools to:

• Track submitted and posted transactions.
• Audit metadata and timestamps.
• Reconcile transaction batches for compliance.

Step 6: Submit corrections via reversals

Do not edit or delete transactions. Submit a reversal instead. Midaz links each reversal to its original transaction for full traceability.

Step 7: Optimize complex workflows

Use multi-operation transactions to:

• Process interest accruals.
• Execute batched payouts.
• Handle conditional flows with routing logic.

Midaz keeps atomicity across all legs. Either the full transaction posts, or nothing does.