> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
### Step 1: [Set up the Organization](/en/reference/midaz/create-an-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](/en/reference/midaz/create-a-ledger)
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](/en/reference/midaz/create-an-asset)
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](/en/reference/midaz/create-an-account-type)
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**](/en/reference/midaz/create-an-operation-route). 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**](/en/reference/midaz/create-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.
### Step 1: [Create a customer Portfolio](/en/reference/midaz/create-a-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](/en/reference/midaz/create-an-account)
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](/en/reference/midaz/create-an-account-type), 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](/en/reference/midaz/create-a-segment)
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](/en/reference/midaz/create-a-transaction-using-json)
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.
### 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.