Accounts

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 non-external Account must use a registered Account Type. You register Account Types for your business classification.

Key characteristics

Each Account links to exactly one Asset.
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. 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 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.
The Ledger creates a canonical external Account automatically when you create an Asset.
The canonical external Account follows a clear naming pattern: @external/<asset-code>, such as @external/BRL.

These accounts 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

The canonical external Account created with an Asset follows the naming pattern @external/<asset-code>. The asset code in that alias acts as the lookup key. You can retrieve this canonical 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 for the canonical external Account. They prepend @external/ to the code you provide, then perform an alias-based lookup. The result is identical to a query by that 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.

{
  "name": "User Checking Account",
  "assetCode": "BRL",
  "alias": "@user_checking_123",
  "entityId": "EXT-ACC-12345",
  "type": "checking"
}

Parent Account ID

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

Blocked accounts

Set blocked to true when you create or update an Account. Midaz then refuses every transaction that moves the Account, as source or destination. The block does not stop the cancellation of a pending transaction. To allow one debit of an exact amount out of a blocked Account, create a single-use block exception. Then send its ID in the accountBlockExceptionId field of the transaction.

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, identify each Account by its account alias. Do not use the account ID. An alias is optional when you create a non-external Account. If you skip it, Midaz uses the account ID as the alias. A user-created external Account requires an alias. The alias you set can have up to 100 characters from a-z, A-Z, 0-9, @, :, _, and -.

Managing Accounts

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

Via API

Create an Account: Open a new Account linked to an Asset.
List Accounts: View all Accounts in a Ledger.
Retrieve an Account: Get details of a specific Account.
Retrieve an Account by Alias: Get details of a specific Account by its alias.
Retrieve an External Account: Get details of a specific External Account by its asset code.
Update an Account: Edit the metadata or settings of an existing Account.
Delete an Account: Delete a specific Account.
Close an Account: Close an Account whose balances are all exactly zero. Midaz keeps its history and refuses any later movement.

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. Midaz also refuses to delete or close an account with a balance that owes fee debt (0527) or that other balances owe fee debt to (0528).

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.

Midaz Core

CRM

Fees

Account structure

Key characteristics

Multiple accounts per customer

External Account

External account codes

Entity ID (external system reference)

Parent Account ID

Blocked accounts

Account aliases

Use the Account Alias in Transactions

Managing Accounts

Via API

Via Lerian Console

​Account structure

​Key characteristics

​Multiple accounts per customer

​External Account

​External account codes

​Entity ID (external system reference)

​Parent Account ID

​Blocked accounts

​Account aliases

​Use the Account Alias in Transactions

​Managing Accounts

​Via API

​Via Lerian Console

Account structure

Key characteristics

Multiple accounts per customer

External Account

External account codes

Entity ID (external system reference)

Parent Account ID

Blocked accounts

Account aliases

Use the Account Alias in Transactions

Managing Accounts

Via API

Via Lerian Console