Skip to main content
In banking terms, an Account represents a financial product, such as a checking account, savings account, or loan account.
Midaz lets you create as many accounts as your structure demands. No caps, no constraints; just the flexibility you need.

​
Account structure

  • Account > Ledger: Accounts are created within a Ledger, which tracks and consolidates all balances and operations.
  • Account > Portfolio: Accounts can be grouped into Portfolios to represent customer clusters, product lines, or business units.
  • Account > Asset: Each Account is linked to a single Asset, defining the type of value it holds—such as BRL, USD, BTC, or loyalty points.
  • Account > Account Type: With Account Type validation enabled, every Account must be categorized by an Account Type that can be created according to specific user needs or business classification.

​
Key characteristics

  • Each Account is linked to exactly one Asset type.
  • Accounts are uniquely identified within a Ledger.
  • All transactions involve debits and credits between Accounts.

​
Multiple accounts per customer

A single customer often holds more than one balance — and Midaz models each as its own Account rather than 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, 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 tracked on its own.
When balance, ledger, statement, or rule differs, each one becomes its own Account — classified by an Account Type, grouped under the customer via a Portfolio, and tied to identity through CRM. Modeling these as one account with labels works until the balances need to diverge; separate accounts keep each one 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’re used to track money that’s coming in or going out, typically tied to users, partners, or financial providers beyond your internal ledger. But they’re more than just placeholders. External accounts:
  • Manage temporary balances during operations involving external parties.
  • Are the only accounts allowed to go negative, which signals that funds are in transit.
  • Are automatically created by the Ledger whenever you create an Asset.
  • Follow a clear naming pattern: @external/<asset-code>, like @external/BRL.
In practice, these accounts act as bridges between your system and the outside world, handling inflows, outflows, and everything in between with clarity and control.
To keep the Ledger accurate and reliable, external accounts cannot be deleted or changed.

​
External account codes

Every external account follows the naming pattern @external/<asset-code>. The asset code in the alias acts as the external account’s lookup key — you can retrieve the account and its balances using convenience endpoints that accept just the asset code:
  • GET .../accounts/external/{code} — Retrieve the external account for an asset code (e.g., BRL resolves to @external/BRL).
  • GET .../accounts/external/{code}/balances — Retrieve balances for that external account.
These endpoints are shortcuts — they prepend @external/ to the code you provide and perform an alias-based lookup. The result is identical to querying by the full alias.

​
Entity ID (external system reference)

The entityId field on any account (not just external accounts) lets you link it to a record in an external system — such as a core banking platform, CRM, or partner system.
  • Not the same as alias: Aliases are used in transactions and must be unique within a ledger. entityId is purely informational — a reference for your integration, not used by Midaz internally.
  • Optional: Set it at creation or via update. Max 256 characters.
  • Use case: When your system already has an account identifier (e.g., EXT-ACC-12345), store it in entityId so you can 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, giving you the flexibility to define the relationship based on your business logic. Whether you use it to represent a traditional parent-child structure or something else entirely, the choice is yours. Midaz provides the foundation—you decide how to build on it.

​
Account aliases

Aliases make it easier to identify accounts by replacing complex IDs with readable, user-friendly labels.
  • For example: Instead of referencing an account like 3172933b-50d2-4b17-96aa-9b378d6a6eac, you can simply use @username_1.

​
Use the Account Alias in Transactions

When creating a transaction, always use the account alias in the account field—not the account ID. Assigning an alias when you create an account is optional. If you skip it, no problem—the system will automatically use the account ID as the alias. Either way, every account ends up with a unique alias. So when it’s time to reference an account in a transaction, just use the alias. Clean, consistent, and ready to go.

​
Managing Accounts

You can manage your Accounts either via API or through Lerian Console.

​
Via API

You cannot deactivate an account with a remaining balance. First, transfer the amount to another account before deactivating it.

​
Via Lerian Console

All Account management actions, including viewing, creating, editing, and deleting, can be done through the Accounts page in the Midaz Module of the Lerian Console. Learn more in the Managing Accounts guide.