> ## 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.

# Accounting

> Comprehensive guide to understanding and implementing accounting principles in Midaz

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](/en/midaz/transaction-routing-entities#4-configure-accounting-entries-actions) 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**](/en/reporter/what-is-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