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

# Setting up accounting in the Console

> Walk through a Console-only guide to build your accounting model in Midaz — from planning a chart of accounts to running your first Pix payment.

This guide shows you how to set up accounting in the Midaz Module of the Lerian Console. You use only the screens and forms in the Console — no code. It is the Console companion to the developer-focused [Accounting Walkthrough](/en/midaz/accounting-walkthrough). You reach the same result, but through **what you click and configure**, not what you send to an API.

It targets product managers, implementation teams, and developers who prefer to model their accounting in the UI. We keep technical terms where they matter. We always explain what they mean when you see them on screen.

<Note>
  You will not see any JSON or API calls here. You do everything below through Console forms. To automate the same setup later, follow the technical reference each section links to.
</Note>

## What you are building

***

Accounting in Midaz uses **double-entry bookkeeping**. You do not do the bookkeeping by hand — the Console and the ledger enforce it for you. Keep one rule in mind:

> Every transaction moves value **from** one place **to** another. One side gives (debit), one side receives (credit), and the two always balance.

You model your accounts and routes once. From then on, the ledger balances every transaction automatically and keeps it auditable.

The setup follows a logical order. Each layer builds on the one before it:

<Steps>
  <Step title="Plan your chart of accounts">
    Decide which balances your product needs (customer funds, fees, settlement, treasury, revenue).
  </Step>

  <Step title="Create Account Types">
    Define the categories that classify your accounts.
  </Step>

  <Step title="Create Accounts">
    Open the actual balance containers, each with a **Type** and an Asset. You select the Type for non-external Accounts; enabling **External account** sets it to `external` automatically. When **Validate Account Type** is enabled, the Type of every non-external Account must match a registered Account Type.
  </Step>

  <Step title="Create Accounting Routes">
    Set the rules for which accounts can join each transaction and how the ledger posts entries.
  </Step>
</Steps>

<Tip>
  Work top to bottom. Routes are much easier to build once you already know which accounts represent customers, treasury, fees, and settlement.
</Tip>

## Step 1 — Plan your chart of accounts

***

In traditional accounting, a **Chart of Accounts (CoA)** is the master list of every account category your business uses: assets, liabilities, revenue, and expenses. It also defines how you classify each movement against those categories.

In Midaz there is **no single "Chart of Accounts" screen to fill in**. Instead, your CoA emerges from the building blocks you create in the Console: Assets, Account Types, and Accounts. You plan it up front, mostly as a paper (or whiteboard) exercise.

Before you open the Console, list the balances your product needs. For a typical payments product that might be:

| Balance you need | What it represents                |
| ---------------- | --------------------------------- |
| Customer funds   | Money your end users hold         |
| Settlement       | Funds waiting to clear            |
| Fee revenue      | Fees you collect                  |
| Fee expense      | Fees you pay to providers         |
| Treasury         | Your own internal operating funds |

This list is your blueprint. The next steps turn each line into something concrete in the Console.

<Note>
  Before any account can exist, it needs an **Asset** — the unit of value it holds (for example `BRL`). If you have not created your assets yet, start with [Creating an Asset](/en/midaz/console/creating-an-asset).
</Note>

## Step 2 — Create your Account Types

***

**Account Types** are the categories that classify your accounts. Think of them as labels like `customer`, `treasury`, or `fee` that group accounts by their role. Later, Accounting Routes use these labels to decide which accounts a transaction can use.

In the Console you create one Account Type per category from your blueprint — not one per individual customer.

<Card title="Create an Account Type" icon="plus" horizontal href="/en/midaz/console/creating-an-account-type">
  Open the New Account Type form and define a category with a clear name and a stable key value.
</Card>

A typical payments setup uses these Account Types:

| Account Type | Use it for                 |
| ------------ | -------------------------- |
| `customer`   | Liquid customer balances   |
| `settlement` | Funds awaiting clearing    |
| `fee`        | Fees collected as revenue  |
| `treasury`   | Internal operations        |
| `expense`    | Fees paid out to providers |

<Warning>
  The **Key Value** of an Account Type (for example `customer`) is what routes and accounts rely on. Keep it short, lowercase, and stable — changing it later means recreating the accounts and routes that depend on it.
</Warning>

<Note>
  The Account Types menu appears only after you enable **Validate Account Type** in your Ledger settings. To turn it on, see [Managing Ledgers](/en/midaz/console/managing-ledgers-via-console#ledger-settings).
</Note>

## Step 3 — Create your Accounts

***

**Accounts** are the balance containers — the things that hold value and that money moves between. Each account has a **Type** and one Asset (its currency). You select the Type for non-external Accounts; enabling **External account** sets it to `external` automatically. When **Validate Account Type** is enabled, the Type of a non-external Account must match a registered Account Type (external Accounts skip this check). A human-readable **alias** identifies it; `@customer_123_brl` is one common convention.

For each line in your blueprint, create one Account in the Console.

<Card title="Create an Account" icon="plus" horizontal href="/en/midaz/console/creating-an-account">
  Open the New Account form, choose its Type and Asset, and give it a clear alias.
</Card>

When you fill in the form, a few choices are permanent and worth getting right the first time:

| Field             | Why it matters                                                                              |
| ----------------- | ------------------------------------------------------------------------------------------- |
| **Account Alias** | The name routes and transactions use to find the account. Cannot be changed after creation. |
| **Type**          | The Account Type that classifies it. Cannot be changed after creation.                      |
| **Asset**         | The currency or unit it holds. Cannot be changed after creation.                            |

<Warning>
  The Console **locks Alias, Type, and Asset when you save the account**. To change any of them, create a new account. Double-check before you save.
</Warning>

### Understanding what a balance actually shows

When you open an account in the Console, its balance is not a single number. Midaz splits every balance into two **buckets**. You always know what you can spend and what the ledger holds back. In plain language:

| Bucket        | What it means when you look at an account                                                                                                                                                           |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Available** | Money that is free to spend or send **right now**. This is the number that goes up and down with normal payments.                                                                                   |
| **On hold**   | Money that a pending operation has **reserved** but not yet finalized. It still belongs to the account. The ledger sets it aside, and you cannot spend it until the hold is confirmed or cancelled. |

Both amounts appear as exact decimal values (for example, `12.50`). There is no scale factor to apply when you read them.

<Note>
  **On hold** powers two-step payments. When you authorize a payment but do not yet capture it, the amount moves from **Available** to **On hold**. Confirming the payment releases it to the destination. Cancelling returns it to Available. You see each of these movements on the account at every stage.
</Note>

## Step 4 — Create your Accounting Routes

***

With **Validate Routes** enabled, each transaction must specify a valid Accounting Route in the ledger. An Accounting Route is a reusable rule for one kind of transaction, such as a *Pix transfer* or a *fee charge*. It answers three questions:

* Which accounts can send on the **source** side?
* Which accounts can receive on the **destination** side?
* Which debit and credit **entries** should the ledger post when it runs?

The Console builds these through a guided 3-step wizard, so you do not have to assemble anything by hand.

<Card title="Manage Accounting Routes" icon="route" horizontal href="/en/midaz/console/managing-accounting-routes">
  See how the Accounting Routes page works and what each part of the wizard does.
</Card>

<Card title="Create an Accounting Route" icon="plus" horizontal href="/en/midaz/console/creating-an-accounting-route">
  Walk through the 3-step wizard to define a route, its operation rules, and its entries.
</Card>

To decide how to shape a route, see [Accounting rules](/en/midaz/console/mc-accounting) — it explains the choices in plain terms. The essentials:

<AccordionGroup>
  <Accordion title="Source, Destination, or Bidirectional?">
    Each rule inside a route applies to one side of a transaction:

    * **Source** — the sending side (where value comes from).
    * **Destination** — the receiving side (where value lands).
    * **Bidirectional** — the same rule applies to both sides, for cases where one kind of account can both send and receive.

    A valid route needs at least one Source **and** one Destination, or a single Bidirectional rule.
  </Accordion>

  <Accordion title="How should an account be validated?">
    Each rule checks accounts in one of two ways:

    * **Account Type** — the rule accepts any account of a given category (for example, any `customer` account can send). Use this for flexible, scalable flows.
    * **@Alias** — the rule accepts only one exact account (for example, only `@fee_revenue` can receive). Use this for fixed operational accounts like treasury, fees, or settlement.
  </Accordion>

  <Accordion title="Which accounting scenario?">
    Scenarios decide how the debit and credit entries get recorded:

    * **Direct** — a one-step movement, posted immediately.
    * **Two-Step** — a hold-then-commit flow. It uses separate entries to reserve, confirm, and cancel funds, and it drives the **On hold** bucket.
    * **Reversal** — entries the ledger records to undo a completed transaction.
    * **Overdraft** — entries the ledger records when a debit exceeds the account's available funds and draws on an overdraft line.
    * **Block** — entries the ledger records when funds on an account are blocked or unblocked.
  </Accordion>
</AccordionGroup>

<Warning>
  Turn on **Validate Routes** in Ledger settings **only after** the routes you need already exist. If validation is on but a matching route is missing, those transactions will fail.
</Warning>

## Putting it together — a simple Pix payment

***

Let's run the whole flow in the Console for a basic **Pix cash-out**: a customer sends BRL out of their wallet to a settlement account. Assume your `BRL` asset already exists.

<Steps>
  <Step title="Create the Account Types">
    From the **Account Types** page, create:

    * `customer` — for end-user balances.
    * `settlement` — for funds leaving to the outside world.

    See [Creating an Account Type](/en/midaz/console/creating-an-account-type).
  </Step>

  <Step title="Create the Accounts">
    From the **Accounts** page, create:

    * `@customer_123_brl` — Type `customer`, Asset `BRL`. The customer's wallet.
    * `@external_brl` — Type `settlement`, Asset `BRL`. Where funds settle when they leave the ledger.

    See [Creating an Account](/en/midaz/console/creating-an-account).

    <Note>
      `@external_brl` is a regular, ledger-owned settlement Account. This example uses it so the route can validate the `settlement` Account Type. It is not the canonical external Account `@external/BRL`, which Midaz creates automatically together with the `BRL` Asset; the `@external/` alias prefix is reserved, so you cannot create that Account yourself. For money that actually enters or leaves Midaz, use `@external/BRL`. See [Common mistakes to avoid](/en/midaz/common-mistakes-to-avoid).
    </Note>
  </Step>

  <Step title="Create the Accounting Route">
    From the **Accounting Routes** page, start the wizard and build a `Pix cash-out` route:

    * A **Source** operation rule validating Account Type `customer` (the wallet sends).
    * A **Destination** operation rule validating Account Type `settlement` (the settlement account receives).
    * A **Direct** accounting scenario, with a debit entry on the source and a credit entry on the destination.

    See [Creating an Accounting Route](/en/midaz/console/creating-an-accounting-route).
  </Step>

  <Step title="Run a transaction">
    Create a transaction that moves, say, `100.00 BRL` from `@customer_123_brl` to `@external_brl` using your `Pix cash-out` route. See [Creating a Transaction](/en/midaz/console/creating-a-transaction).
  </Step>

  <Step title="Check the result">
    Open each account and look at the balance:

    * `@customer_123_brl` — **Available** drops by `100.00`.
    * `@external_brl` — **Available** rises by `100.00`.

    Both movements share the same transaction, giving you a clean, balanced audit trail.
  </Step>
</Steps>

<Tip>
  Need an authorize-then-capture flow instead of an instant one? Use a **Two-Step** scenario on the route. You will then watch the amount move into **On hold** when reserved, and out of it when you confirm or cancel.
</Tip>

## What to do next

***

You now have a working accounting model, built entirely in the Console. To go deeper, use these technical references. They cover how to automate the setup, understand the entities, and turn ledger activity into reports:

<Card title="Accounting Walkthrough (developer)" icon="code" href="/en/midaz/accounting-walkthrough">
  The end-to-end developer version of this guide, including the data model and double-entry detail.
</Card>

<Card title="Accounting overview" icon="book" href="/en/midaz/accounting-in-midaz">
  How the core accounting primitives relate to one another.
</Card>

<Card title="Transaction Routing entities" icon="route" href="/en/midaz/transaction-routing-entities">
  The technical model behind Accounting Routes, operation routes, and entries.
</Card>

<Card title="Balances" icon="scale-balanced" href="/en/midaz/balances">
  The full balance model behind available and on-hold amounts.
</Card>