The Data Model Behind Midaz

---

Midaz is built around a structured yet flexible data model, designed to give financial institutions full control over their operations. Understanding its core entities and how they interact is key to designing an efficient and scalable financial system.

At the foundation are Organizations, Ledgers, Accounts, Portfolios, Segments, and Assets. Together, they create a structured hierarchy that mirrors a bank’s internal operations while providing the flexibility needed to adapt to different use cases.

Organizations

An Organization is the top-level entity in Midaz, representing a financial institution such as a bank or fintech. It owns and governs the financial data within the platform, acting as the primary container for all financial operations.

In practical terms, a bank or financial group would register as an Organization in Midaz, establishing a structured environment for its operations.

Sub-Organizations

Organizations can establish parent-child hierarchies, enabling banks to represent subsidiaries, regional branches, or different business units within the same framework.

This hierarchical structure is ideal for financial groups that operate multiple legal entities but still require centralized oversight. Each entity can have its own set of Ledgers, ensuring operational independence while maintaining a consolidated view at the group level.

Organization Structure

• Organization > Ledgers: Every Organization can own multiple Ledgers. All financial records—such as accounts and transactions—are maintained within Ledgers that belong to a specific Organization.

Key Characteristics

• Organizations are the highest level in the hierarchy.
• Each Organization governs its own Ledgers, defining operational boundaries.

Ledgers

A Ledger acts as the Organization’s financial backbone, maintaining a precise record of all Transactions and Operations. Every financial event—deposits, withdrawals, transfers, fees—is tracked within a Ledger, ensuring complete traceability and control.

Organizations can use multiple Ledgers to segregate financial operations. For example, a bank may maintain separate Ledgers for different business lines, geographies, or regulatory requirements. Alternatively, a single Ledger can handle all operations for a streamlined approach.

Ledger Structure

• Ledger > Organization: Each Organization can own multiple Ledgers, but each Ledger belongs to only one Organization. This ensures financial separation and accountability.
  • Multiple Ledgers should only be used when data or operational segregation is required—for example, for internal treasury operations versus customer accounts.

🚧

Important Note

Transactions cannot occur directly between Ledgers without orchestration. If you need to manage cross-ledger transactions, you must implement appropriate workflows to ensure consistency.

Key Characteristics

• Ledgers ensure financial integrity and operational transparency.
• All Accounts and Transactions exist within a Ledger, forming a complete financial system.
• Each Ledger maintains a balanced set of Accounts.
• Multiple Ledgers can be used for segmentation, but cross-ledger transactions require explicit handling.

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.

Child Accounts

Accounts can be structured in a parent-child relationship, where Child Accounts roll up into a primary Account. This enables granular financial tracking and categorization.

For instance, a corporate client might have a main account with Child Accounts for different departments or projects. This setup simplifies fund management while maintaining clear financial oversight.

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.

Portfolios

A Portfolio is a logical grouping of Accounts belonging to a single entity, such as a customer or business unit. Portfolios simplify account management by clustering all related Accounts under a single structure.

Think of a Portfolio as a wallet containing multiple asset-specific Accounts for a customer.

For example, a retail banking customer might have a Portfolio that includes:

• A BRL checking account
• A USD savings account
• A credit card account

This grouping enables institutions to view a customer’s total relationship across all accounts and apply policies at the Portfolio level.

Portfolio Structure

• Portfolio > Accounts: Each Portfolio contains one or more Accounts, typically linked to a specific customer or entity.
• Portfolio > Ledger > Organization: Portfolios belong to an Organization via their Ledger, providing structured account management.

Key Characteristics

• Portfolios commonly represent customers in a banking context.
• They simplify financial aggregation, enabling customer-level insights.
• Internal Portfolios can also be created for operational use cases.

Segments

A Segment is a way to categorize Accounts or Portfolios based on shared attributes, enabling targeted financial operations and services.

Banks use Segments to create differentiated experiences—for example:

• Premium Segments (e.g., Black or Diamond customers) with enhanced benefits like fee waivers and premium support.
• Student Accounts with special perks such as cashback on education-related purchases.

Segments allow institutions to dynamically group accounts and apply customized policies with minimal friction.

Segment Structure

• Segment > Accounts: Accounts (or Portfolios) are tagged with a segment_id to apply specific rules or benefits.
• Segments operate across Portfolios and Ledgers, providing flexible categorization.

Key Characteristics

• Segments can be defined at the Organization or Ledger level.
• They provide a scalable way to enforce tailored policies across customer groups.
• A Segment can include multiple Accounts or Portfolios, offering broad applicability.

Assets

Assets represent the financial instruments or currencies that Accounts hold. Every Account is linked to exactly one Asset.

Assets can include:

• Currencies (e.g., BRL, USD, EUR)
• Cryptocurrencies (e.g., BTC, ETH)
• Non-currency assets (e.g., gold, loyalty points, tokenized securities)

Each Asset is managed independently within the Ledger, ensuring that balances remain clearly defined.

🚀

Exchange Engine

The Midaz Exchange Engine enables seamless transactions between Accounts holding different Assets. By integrating external data sources for exchange rates, it manages spreads, conversions, and risk parameters dynamically.

Asset Structure

• Asset > Account: Every Account is tied to a single Asset.
• Asset > Ledger > Account: Assets are defined at the Ledger level, and Accounts are created based on available Assets.

Key Characteristics

• Assets must be explicitly defined before use.
• Each Asset has a unique identifier, such as a currency code.
• Multi-asset operations are handled through structured conversions.

Midaz Hierarchy

---

Midaz provides a structured yet adaptable financial architecture:

• Organizations manage one or more Ledgers.
• Each Ledger contains multiple Accounts, each linked to a specific Asset.
• Portfolios group Accounts under a single entity.
• Segments overlay on Accounts or Portfolios, enabling flexible categorization.

This model ensures financial institutions can build scalable, compliant, and highly customizable financial ecosystems—without constraints.

Transactions and Financial Flow

---

At the heart of Midaz is a powerful double-entry accounting system that ensures every financial movement is precise, reliable, and balanced. Every Transaction consists of at least two Operations, where every debit has an equivalent credit. This guarantees financial integrity and prevents inconsistencies.

This section breaks down how transactions are structured, how funds move through accounts, and how Midaz’s Chart of Accounts enables seamless financial routing.

Transactions

A Transaction in Midaz represents a complete financial event, often involving multiple accounts. Transactions inherently follow double-entry principles, ensuring that every operation is counterbalanced.

Double-Entry Accounting

Midaz enforces a fundamental rule: the sum of debits must equal the sum of credits. This structure guarantees financial accuracy and eliminates imbalances.

For example, if a customer transfers $100 from their savings to their checking account, Midaz records:

• a $100 debit from the savings account
• a $100 credit to the checking account

This way, the Ledger remains balanced. This built-in structure provides accuracy and prevents inconsistent balances.

N:N Transactions (Many-to-Many)

Unlike traditional financial systems that limit transactions to one-to-one or one-to-many relationships, Midaz enables N:N transactions, allowing multiple source and destination accounts within a single transaction.

Consider a marketplace payout where multiple sellers (several source accounts) are paid from a single escrow account, and each seller might also pay a fee to the platform. This could be modeled as one transaction involving many parties on both sides. Midaz can handle such a scenario in one atomic transaction, crediting and debiting all relevant accounts.

Another example is a peer-to-peer payment with fees: one transaction can debit the payer’s account and credit both the payee’s account and a fee account in one go. This capability simplifies financial flows that would otherwise require multiple steps.

Atomicity and Integrity

Transactions are atomic operations – either all constituent operations succeed, or none do. This ensures that partial financial events do not occur. If any part of a transaction fails validation (say, insufficient funds in one account), the entire transaction will not be applied, preserving ledger integrity.

Operations

An Operation is the smallest unit of financial activity in Midaz – essentially a single ledger entry, which is either a debit or a credit on a specific account.

Operations are the building blocks of transactions. Each operation records a change in the balance of one account:

• A Debit operation decreases an account’s balance (for asset accounts that normally have positive balances) or represents value outflow from that account.
• A Credit operation increases an account’s balance or represents value inflow into that account.

Every transaction is composed of two or more operations. If we break down a transaction, it’s a collection of operations that together must net to zero from the ledger’s perspective. For example, a P2P payment with a fee might include:

• a $100 debit from the sender’s account
• a $98 credit to the recipient’s account
• a $2 credit to the platform’s fee account

Midaz guarantees that transactions always balance before they are committed.

Operations also carry metadata such as timestamps and references to the transaction they belong to. In Midaz's API or DSL, when creating a transaction, you must specify a set of operations, each with an amount, asset, source/destination account, and so on, and the system validates that they balance out before committing.

Chart of Accounts

The Chart of Accounts in Midaz defines the accounting routes and categorizations of Operations within transactions. It acts as a structured framework, ensuring financial activities are categorized, auditable, and aligned with regulatory requirements.

📘

Note

The Chart of Accounts links the Ledger to a traditional balance sheet. For instance, a Controller can define that all fees related to a specific type of transaction will be credited to a "X Fees Account," ensuring proper categorization within financial statements.

In Midaz, each operation can be tagged with a specific route or category as defined by the chart of accounts. This provides a clear and auditable structure for all financial flows, critical for compliance and reporting in banking environments.

Defined Routes

The chart of accounts allows defining routes such as "Fee Income", "Interest Expense", or "Customer Deposits". By tagging a fee operation with the "Fee Income" route, Midaz automatically credits the correct ledger account, streamlining financial reporting.

Consistency

Using a Chart of Accounts ensures uniform transaction categorization, simplifying audits and reporting. For example, auditors can filter all operations tagged as "Interest Income" to track bank interest payouts and their corresponding debits.

Settlement Flows

The chart-of-accounts helps define settlement flows for external transactions. For example, when funds leave Midaz via SWIFT or PIX transfers, they are recorded under a dedicated "external settlement" account, ensuring a balanced ledger representation.

Chart-of-Accounts Group

For institutions operating multiple ledgers or product lines, Midaz supports Chart-of-Accounts Groups. This allows banks to manage financial flows under distinct structures while maintaining a unified reporting approach.

Best Practices for Structuring a Bank’s Operations in Midaz

---

Implementing Midaz in a banking environment requires a strategic approach to entity hierarchy and account structuring. Below are best practices to optimize the setup of organizations, ledgers, accounts, portfolios, and segments for operational efficiency and scalability.

Optimal Hierarchy of Organizations and Ledgers

Single vs. Multiple Organizations

Banks operating as a single legal entity typically require one Organization in Midaz. However, for banking groups with subsidiaries, a hierarchical structure is recommended, with a parent organization overseeing multiple child organizations. This setup aligns with corporate governance and enables data segregation per entity.

📘

Note

The organization structure should reflect your corporate structure.

Using Multiple Ledgers

Within an organization, decide how many ledgers to use based on operational needs. A common approach is to maintain a primary ledger for customer transactions while using additional ledgers for specialized purposes, such as treasury operations or regulatory segmentation.

📘

Note

Use multiple ledgers only when necessary to minimize complexity. Transfers between ledgers require external flow orchestration via APIs.

Efficient Account Structuring for Retail and Corporate Banking

Retail Customers – Portfolio per Customer

For retail banking, best practice is to create a Portfolio for each customer, containing individual accounts for different asset types (e.g., checking, savings, credit card). This setup allows efficient balance retrieval and streamlined operations.

🚀

Entity Registry

The Entity Registry plugin manages personal data such as tax IDs, addresses, and banking aliases.

Corporate Clients – Hierarchical Accounts

For corporate banking, utilize child accounts within portfolios to reflect internal structuring. A company might have a parent account for its main funds and child accounts for subdivisions like payroll or expense tracking.

Internal Accounts

Establish internal accounts for revenue, expenses, and settlement flows. Dedicated accounts for "Fee Income – USD" or "Interest Expense – USD" ensure clear financial reporting.

Streamlining Financial Operations

---

By structuring Organizations, Ledgers, Accounts, Portfolios, and Segments strategically, Midaz ensures a streamlined financial ecosystem. A well-planned architecture simplifies operations, enhances scalability, and strengthens compliance—allowing institutions to maintain control and agility in an evolving financial landscape.