Guides

Accounts

Suggest Edits

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.


Account Structure

  • Account > Ledger: Accounts exist within a Ledger.
  • Account > Portfolio: Accounts can be grouped into Portfolios for customer or business-level aggregation.
  • Account > Asset: Each Account is linked to one Asset, ensuring balance clarity. For example, an Account could be denominated in BRL, USD, or represent a specific asset like gold, bitcoin, or loyalty points.

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.

Account Types

Each account type determines how it behaves and what role it plays within the Ledger:

  • Deposit: The go-to account for everyday transactions, from checking balances to making payments.
  • Savings: Perfect for investments, with potential earnings (like interest) when the Interests plugin is enabled.
  • Loans: Keeps track of client loans and automates calculations when the Interests plugin is in use.
  • Marketplace: Designed for installment-based sales (think five-month payment plans), plus settlement and receivables advance products.
  • Credit Card: Tracks credit card balances, payments, and usage in one place.
  • External Accounts: Handles money moving in and out of the Ledger. These accounts:
    • Manage temporary balances.
    • Are the only type allowed to have a negative balance (indicating funds in transit).
    • Are automatically generated by the Ledger when an Asset is created.
    • Follow the naming convention @external/<asset-code>, for example, @external/BRL.

🚧

External Accounts Are Non-Modifiable

To keep the Ledger accurate and reliable, external accounts can’t be deleted or changed.


Account Behaviors

The table below outlines the modifiability and behaviors for each account type:

TypeDeactivatedEditedNegative Balance Allowed
Deposit

Savings

Loans

Marketplace

Credit Card

External Accounts


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

To manage your Accounts you can use the Accounts API or the Portfolios and Accounts tab of the Ledgers page on Midaz Console.


View Accounts Details

  • Via API:
  • Via Console: Access the Portfolios and Accounts tab to view the details of a Portfolio. For more information, refer to the Managing Accounts page.

Create an Account


Edit an Account


Delete an Account

  • Via API: Use the Update an Account endpoint.
  • Via Console: Delete an Account from the Portfolios and Accounts tab of the Ledgers page. For more information, refer to the Deleting an Account page.

Managing Portfolio Accounts

You can use the following endpoints to manage accounts directly from the Portfolio:

🚧

Attention

These endpoints will soon be deprecated.

Updated 8 days ago