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

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.

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:

1. Plan your chart of accounts

   Decide which balances your product needs (customer funds, fees, settlement, treasury, revenue).

2. Create Account Types

   Define the categories that classify your accounts.

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

4. Create Accounting Routes

   Set the rules for which accounts can join each transaction and how the ledger posts entries.

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

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.

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.

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.

Create an Account Type

Open the New Account Type form and define a category with a clear name and a stable key value.

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

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.

The Account Types menu appears only after you enable Validate Account Type in your Ledger settings. To turn it on, see Managing Ledgers.

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.

Create an Account

Open the New Account form, choose its Type and Asset, and give it a clear alias.

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.

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.

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.

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.

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.

Manage Accounting Routes

See how the Accounting Routes page works and what each part of the wizard does.

Create an Accounting Route

Walk through the 3-step wizard to define a route, its operation rules, and its entries.

To decide how to shape a route, see Accounting rules — it explains the choices in plain terms. The essentials:

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.

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.

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.

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.

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.

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

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

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

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

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

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

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.

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:

Accounting Walkthrough (developer)

The end-to-end developer version of this guide, including the data model and double-entry detail.

Accounting overview

How the core accounting primitives relate to one another.

Transaction Routing entities

The technical model behind Accounting Routes, operation routes, and entries.

Balances

The full balance model behind available and on-hold amounts.