Guides
Start typing to search…

Accounts

An Account is the core financial unit within a Midaz Ledger. Each Account is linked to a specific Asset (such as a currency or financial instrument) and tracks all debits, credits, and balances for that Asset.

In banking terms, an Account represents a financial product, such as a checking account, savings account, or loan account.

👍

Tip

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.

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.

❗️

Important

To keep the Ledger accurate and reliable, external accounts cannot be deleted or changed.

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.

Account types

Account Types in Midaz allow you to systematically classify accounts according to your organization's financial structure needs. These classifications define the nature and purpose of accounts within your ledger design, enabling proper transaction routing and operational validation across different account categories.

Account Types can be customized via the Account Types API to match your specific business requirements and financial workflows, providing the foundation for structured transaction processing while maintaining data integrity.

Enabling Account Type validation

In case you want to activate account type validation to a specific ledger, you must configure it in the Onboarding service. This means updating the variable in the .env file of Midaz Onboarding service where you want to use type validation.

Your configuration should look like this:

# List of <organization-id>:<ledger-id> separated by comma
ACCOUNT_TYPE_VALIDATION=

Behavior of the type field in Accounts API

When creating an Account, the type field behavior adapts based on the activation of the Account Type Validation feature:

  • Account Type Validation Disabled (Default): The type field is optional and accepts any free-form string.
  • Account Type Validation Enabled: The type field becomes mandatory and must match one of the Account Types previously registered via the Account Types API. If an invalid or non-registered type is submitted, the system will return a validation error.
👍

Tip

If your organization is enabling the Account Type Validation feature, we recommend reviewing existing accounts. You may need to either recreate them or retroactively assign the appropriate Account Type to align with your accounting structure.

This dynamic ensures that every account aligns with the formal accounting categories required by your business, strengthening governance and financial reporting.

Managing Account Types

You can manage your Account Types exclusively via API.


Managing Accounts

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

Via API

🚧

Important

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

Via Console

All Account management actions, including viewing, creating, editing, and deleting, can be done through the Accounts page in the Midaz Console.

Learn more in the Managing Accounts guide.

Updated about 5 hours ago