Skip to main content
An Account is the core financial unit of a Midaz Ledger. Each Account links to one Asset and records every debit, credit, and balance for that Asset. In banking terms, an Account is a financial product, such as a checking account, a savings account, or a loan account.
Midaz does not limit how many accounts you create. Create as many as your structure needs.

​
Account structure

  • Account > Ledger: You create an Account within a Ledger. The Ledger tracks and consolidates all balances and operations.
  • Account > Portfolio: You can group Accounts into Portfolios to represent customer clusters, product lines, or business units.
  • Account > Asset: Each Account links to a single Asset. The Asset defines the type of value the Account holds, such as BRL, USD, BTC, or loyalty points.
  • Account > Account Type: When you enable Account Type validation, each Account must use a registered Account Type. You register Account Types for your business classification.

​
Key characteristics

  • Each Account links to exactly one Asset type.
  • Each Account has a unique identifier within a Ledger.
  • Every transaction records debits and credits between Accounts.

​
Multiple accounts per customer

A single customer often holds more than one balance. Midaz models each balance as its own Account, not as labels on a shared one. The guiding rule: create a separate account whenever a balance needs its own truth. The same customer might hold balances that behave differently:
  • Different nature — a main balance, a benefit balance, or a promotional balance.
  • Different operational rules — a court-ordered or blocked account that accepts inflows but restricts outflows.
  • Separate statement and reconciliation — a product sub-account or pocket that you track on its own.
When the balance, ledger, statement, or rule differs, each one becomes its own Account. You classify it by an Account Type, group it under the customer with a Portfolio, and tie it to identity through CRM. One account with labels works until the balances diverge. Separate accounts keep each balance accurate from the start.
For the full reference architecture — one customer, many accounts, with step-by-step examples — see Midaz for multi-account customers.

​
External Account

External Accounts in Midaz represent accounts outside your organization’s structure. They track money that enters or leaves your ledger, usually to and from users, partners, or financial providers. External accounts have these characteristics:
  • Hold the counterparty balance for money that enters or leaves your ledger.
  • Are the only accounts that can hold a negative balance. The balance can go negative as value moves between your ledger and external parties.
  • The Ledger creates them automatically when you create an Asset.
  • Follow a clear naming pattern: @external/<asset-code>, such as @external/BRL.
In practice, these accounts act as the bridge between your system and the outside world. They record inflows and outflows at the ledger boundary.
Do not try to delete or change an external account. Midaz blocks these operations to keep the Ledger accurate and traceable.

​
External account codes

Every external account follows the naming pattern @external/<asset-code>. The asset code in the alias acts as the lookup key. You can retrieve the account and its balances with convenience endpoints that accept only the asset code:
  • GET .../accounts/external/{code} — Retrieve the external account for an asset code (for example, BRL resolves to @external/BRL).
  • GET .../accounts/external/{code}/balances — Retrieve the balances for that external account.
These endpoints are shortcuts. They prepend @external/ to the code you provide, then perform an alias-based lookup. The result is identical to a query by the full alias.

​
Entity ID (external system reference)

The entityId field exists on any account, not only external accounts. It links the account to a record in an external system, such as a core banking platform, a CRM, or a partner system.
  • Not the same as alias: You use the alias in transactions, and it must be unique within a ledger. The entityId is only a reference for your integration, and Midaz does not use it to move value.
  • Optional: Set it when you create the account or when you update it. The maximum length is 256 characters.
  • Use case: When your system already has an account identifier, such as EXT-ACC-12345, store it in entityId. You can then map between Midaz and your source of truth.

​
Parent Account ID

The Parent Account ID links two accounts within Midaz. You define the relationship based on your business logic. You can use it for a traditional parent-child structure or for another relationship that your business needs.

​
Account aliases

An alias replaces a complex account ID with a readable label. This makes accounts easier to identify.
  • For example: Instead of the ID 3172933b-50d2-4b17-96aa-9b378d6a6eac, you can use @username_1.

​
Use the Account Alias in Transactions

When you create a transaction, always use the account alias in the account field. Do not use the account ID. An alias is optional when you create an account. If you skip it, Midaz uses the account ID as the alias. Every account then has a unique alias.

​
Managing Accounts

You can manage your Accounts through the API or the Lerian Console.

​
Via API

Transfer any remaining balance to another account before you delete an account. Midaz does not delete an account or sub-account that still holds a balance.

​
Via Lerian Console

You can view, create, edit, and delete Accounts on the Accounts page. This page is in the Midaz module of the Lerian Console. Learn more in the Managing Accounts guide.