Accounting rules

Learn how Accounting Routes decide which Accounts join a transaction and how debit and credit entries are posted for each transaction type in Midaz.

The Accounting section is where you define optional rules for transactions.

You do this through Accounting Routes. An Accounting Route is a reusable rule for one kind of transaction, such as a Pix transfer, a card purchase, or a fee charge. Each route answers three questions:

• Which accounts can act on the source side?
• Which accounts can act on the destination side?
• Which debit and credit entries does the route post when the transaction runs?

Example. A Pix transfer route can require a customer account on the source side and a merchant account on the destination side. The route then defines direct debit-and-credit entries between them. When route validation is enabled, a Pix transaction that references the route validates the accounts and applies the configured rules.

Accounting Routes provide optional route validation. Midaz enforces them only when the Ledger setting accounting.validateRoutes is enabled (default false). When enabled, transactions must reference valid routes and operations must match configured rules. Routes are easier to model when you already know which accounts represent customers, treasury, fees, settlement, revenue, and expenses.

How the pieces fit together

---

Piece	What it controls	Example
Accounting Route	The transaction-level route that groups the operation rules.	Pix transfer route
Operation Route	The account side and validation rule.	Source must be customer, Destination must be merchant
Validation rule	How Midaz decides whether an account can be used.	Account Type customer or alias @treasury_main
Accounting scenario	Which debit and credit entries are posted for the transaction lifecycle.	Direct, Two-Step, Reversal, Overdraft, Block/Unblock

Choosing the operation type

---

Use Source when the rule applies only to the sending side

Use Source for accounts where value originates.

Example: a customer account can send funds in a payment flow.

Use Destination when the rule applies only to the receiving side

Use Destination for accounts where value lands.

Example: a merchant account can receive funds in a payment flow.

Use Bidirectional when the same rule applies to both sides

Use Bidirectional when the same account class can send and receive.

Example: checking accounts can transfer value to other checking accounts.

A route must include a Source and a Destination operation route, or at least one Bidirectional operation route.

Choosing the validation rule

---

Validation type	Use when	Example
Account Type	Any account in a class should be valid.	Any customer account can send.
Alias	Only one exact account should be valid.	Only @treasury_main can send.

An Operation Route can optionally include an account rule—registered Account Types or an @Alias. Midaz enforces a present rule when route validation is enabled. Use Account Type validation for scalable flows. Use alias validation for fixed operational accounts, such as treasury, fee, settlement, or suspense accounts.

Common route patterns

---

Customer to merchant

Use separate Source and Destination routes when each side has a different role.

Operation route	Validation
Source	Account Type customer
Destination	Account Type merchant

Peer-to-peer transfer

Use a Bidirectional route when the same account type can be both source and destination.

Operation route	Validation
Bidirectional	Account Type customer

Fee collection

Use a Destination route with alias validation when fees must always land in one operational account.

Operation route	Validation
Source	Account Type customer
Destination	Alias @fee_revenue

Accounting scenarios

---

Scenario	Use when	What the user configures
Direct Transaction	The movement is executed in one step.	Debit and credit entries for immediate posting.
Two-Step Transaction	The movement has hold, commit, and cancel phases.	Entries for reservation, confirmation, and cancellation.
Reversal	A completed transaction may need to be reversed.	Debit and credit entries for the reversal event.
Overdraft	A debit may exceed the account’s available funds, drawing on an overdraft line.	Debit and credit entries for the overdraft draw and later repayment.
Block/Unblock	Funds need to be held and later released on the account’s balance. Available for all route types (tab label “Block”).	Entries for the block (hold) and unblock (release) events.

Do not enable route validation in Ledger settings until the required routes exist. If you enable it without matching routes, transactions fail validation.

Available pages

---

Setting up accounting in the Console

A step-by-step, Console-first guide to building your accounting model — from chart of accounts to a working Pix payment, no API calls required.

Manage Accounting Routes

Configure accounting routes with operation rules and accounting scenarios in a unified wizard.