Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

Midaz provides a modern accounting foundation designed for real-time financial systems. It combines the robustness of traditional double-entry bookkeeping with the flexibility required for digital products, embedded finance, and high-volume operations. This page introduces the core accounting principles inside Midaz, how its primitives map to standard accounting practices, and how you can design a complete chart of accounts using the platform. Midaz is intentionally ledger-centric: every balance, movement, posting, and reconciliation is enforced at the ledger level—offering traceability, auditability, and consistency by default.

​

1. Core accounting concepts in Midaz

---

Before diving into how Midaz implements accounting, it helps to revisit how accounting works conceptually in any financial system.

​

Double-Entry accounting

Midaz is built on strict double-entry rules:

• Every transaction must have at least one debit and one credit.
• Total debits must equal total credits.
• Every movement impacts the ledger in a balanced way.

This ensures:

• No drift in balances
• Precise audit trails
• Regulation-ready financial statements

​

Chart of Accounts

In traditional accounting, the Chart of Accounts (CoA) defines:

• Account categories (Assets, Liabilities, Equity, Income, Expenses)
• Hierarchies
• How movements are classified

Midaz provides tools so your product can mirror or adapt this structure digitally.

​

Accounting events & postings

Every change in value generates an event that contains:

• What happened
• Which accounts were affected
• How much was moved
• Metadata for audit and compliance

Midaz translates business actions (“cash-out”, “fee”, “capture”, “settlement”) into structured accounting postings.

​

2. How Midaz implements accounting

---

Midaz implements accounting using a set of flexible primitives:

• Assets
• Account Types
• Accounts
• Segments
• Portfolios
• Operation Routes
• Transaction Routes
• Transactions

Together, they form a programmable accounting engine.

​

Assets

An asset defines what is being moved:

• Currencies (BRL, USD, EUR)
• Points or miles
• Crypto tokens
• Internal units of value (credits, balance tokens)

Assets define:

• Decimal precision
• Regulatory metadata
• Operational formatting

Midaz enforces asset consistency across all postings.

​

Account types

Account Types represent templates for the accounts in your ledger. Examples:

• CASH
• CUSTOMER_FUNDS
• FEES
• RESERVES
• TREASURY
• RECEIVABLES

Each type defines how accounts behave in terms of:

• Allowed operations
• Association with entities or portfolios
• Internal vs external accounts
• Reconciliation rules

You can define your own account types to reflect your financial model.

​

Accounts

An account represents a balance container inside the ledger. Every account belongs to:

• A portfolio
• A segment
• An account type
• An asset code

Midaz allows:

• Hierarchical accounts
• Multiple balances per account (via balance keys)
• External accounts (e.g. @external/BRL)
• Alias-based routing

This makes it possible to model anything from simple wallets to complex liquidity structures.

​

Segments

Segments allow you to categorize and isolate accounts. Use cases:

• Separate customer funds from internal funds
• Manage business units
• Implement multi-tenant separation
• Track different product lines

Segments are powerful for governance and reporting.

​

Portfolios

Portfolios group accounts that share a common purpose or belong to the same entity. Portfolios help you:

• Associate all customer accounts to a single portfolio
• Isolate legal entities
• Track the financial performance of a group

Midaz allows multiple portfolios per entity depending on your model.

​

Operation routes

Operation Routes define the accounting logic itself. They answer the question:

“When this type of operation occurs, which accounts should be debited and credited?”

For example:

• A transfer out (cash-out)
• A deposit (cash-in)
• A fee collection
• A settlement
• A reversal

Each route describes:

• Source accounts
• Destination accounts
• Balance keys
• Ledger logic
• Validation rules

Operation Routes can also include Accounting Entries — structured rubrics that define how debit and credit entries are recorded for each type of transactional event (direct, hold, commit, cancel, revert). See Transaction Routing for details. Operation Routes are the core of accounting governance in Midaz.

​

Transaction routes

Transaction Routes define the business event that triggers accounting. If Operation Routes define how movements occur, Transaction Routes define when. Examples:

• PIX_CASH_OUT
• PIX_INSTANT_PAYMENT
• PIX_REFUND
• WALLET_TRANSFER
• BANK_SLIP_SETTLEMENT

Each Transaction Route maps a business action to:

• Required validations
• Operational context
• The associated Operation Routes

This gives your system both flexibility and control.

​

3. Building your Chart of Accounts in Midaz

---

Midaz gives you all the primitives to design a complete chart of accounts. Below is a recommended process.

​

Step 1 — Map your financial model

List the types of balances needed:

• Customer balances?
• Internal accounts?
• Reserve or settlement accounts?
• Fee and revenue accounts?

This becomes your initial CoA blueprint.

​

Step 2 — Define account types

For each conceptual category, create an Account Type. Example:

• CASH → liquid customer funds
• SETTLEMENT → funds awaiting clearing
• FEE_REVENUE → fees collected
• FEE_EXPENSE → provider fees
• TREASURY → internal operations

Account Types keep your ledger consistent.

​

Step 3 — Create segments & portfolios

Segments separate business domains. Portfolios manage ownership and grouping. Example:

• Segment: CUSTOMER_FUNDS
• Portfolio: customer_12345_wallet

This allows multi-product and multi-tenant architectures.

​

Step 4 — Create accounts

For each logical balance, create a ledger account. Examples:

• Customer BRL account
• Corporate treasury account
• Provider fee expense account
• Merchant settlement account

Accounts are identified by alias, making routing more intuitive.

​

Step 5 — Define operation routes

Operation Routes map accounting logic to real transactions. Example for a Pix cash-out:

• Debit: customer BRL account
• Credit: external BRL account (@external/BRL)

Midaz ensures:

• Balances exist
• Debits ≤ available balance
• Assets match
• Ledger stays balanced

​

Step 6 — Define transaction routes

Transaction Routes represent your business operations. Each route:

• References Operation Routes
• Defines validations
• Can enforce business rules

This creates a programmable financial brain.

​

4. How Midaz helps with accounting

---

Midaz is designed to make accounting automatic, traceable, auditable, and extensible.

​

Real-Time ledger

Every transaction:

• Updates balances instantly
• Creates immutable audit logs
• Generates metadata for reconciliation
• Ensures double-entry correctness

​

Deterministic financial logic

Operation Routes and Transaction Routes prevent:

• Incorrect debits
• Drifting balances
• Unauthorized account usage
• Inconsistent postings

Your team never needs to manually handle accounting logic in code.

​

Multiple balances per account

Balance Keys let you separate:

• Blocked vs available funds
• Pending vs settled amounts
• Limits
• Multi-currency overlays

Perfect for Pix, cards, and payments.

​

Reversals & adjustments

Midaz supports:

• Transaction reversals
• Refunds
• Chargebacks
• Financial corrections

All with full traceability.

​

Full audit trail

Every movement stores:

• Origin
• Route
• Metadata
• Parent transaction (when applicable)

Regulators love this. Your auditors will too.

​

5. Typical accounting scenarios with Midaz

---

​

Pix Cash-Out

• Customer account is debited
• External settlement account is credited
• Ledger stays balanced
• SPI flow reconciles automatically

​

Pix refund

• A reversal transaction mirrors the original
• Parent transaction is linked
• Compliance rules are enforced

​

Marketplace escrow

• Funds collected into a holding account
• Fees allocated transparently
• Merchant settlements triggered via Operation Routes

​

Fee Engine

• Fee revenue and fee expense accounts automatically updated
• No manual intervention needed

​

6. Next Steps — From accounting to reporting with Reporter

---

Accounting alone does not close the loop — financial data must be transformed into structured, auditable, and regulatory — compliant reports. This is where Lerian Reporter becomes a natural extension of Midaz’s accounting layer. Reporter consumes ledger events, portfolios, segments, balances, and transaction metadata to produce high-fidelity financial outputs, aligned with your operational and regulatory needs.

​

How Reporter fits into your accounting workflow

Reporter acts as a data extraction and transformation engine, designed to turn Midaz’s structured ledger into:

• Daily operational reports
• Reconciliation files
• Financial statements
• Compliance outputs
• Provider integrations

Its design ensures consistency between what happens in the ledger and what your business reports externally.

​

COSIF and regulatory alignment

If your institution needs to comply with COSIF (Brazilian accounting standard) or similar regulatory frameworks, Reporter provides:

• A flexible mapping layer to translate ledger accounts and segments into COSIF lines
• Support for hierarchical structures
• Automated grouping and aggregation rules
• Deterministic outputs suitable for regulatory submission

Midaz manages the accounting logic. Reporter transforms that logic into regulatory-grade files.

​

Why use Reporter alongside Midaz?

Together, they close the accounting cycle:

1. Midaz Ledger ensures structured, real-time, double-entry financial events.
2. Transaction Routes and Operation Routes provide deterministic accounting behavior.
3. Reporter extracts, aggregates, and composes financial and regulatory artifacts.

This gives your institution:

• Full traceability
• Audit-ready records
• Consistent financial narratives
• Seamless COSIF mapping
• Automated compliance workflows