Why this matters
For product and operations teams, Transaction Routes mean predictable, auditable Pix flows without relying on application-level enforcement. Every transaction carries a reference to the route it followed, making compliance reviews and incident investigations straightforward. For engineering teams, routes eliminate repetitive validation code. Instead of checking account types and fee destinations in every Pix integration, you configure the rules once and let Midaz handle enforcement at the ledger level.
| Without Routes | With Routes |
|---|---|
| Each integration must enforce its own account rules | Define the rules once, reuse across all Pix transactions |
| No automatic validation — constraints live in application code | Midaz rejects transactions that don’t match the route’s rules |
| Adding fees requires changes across every Pix integration | Add a new Operation Route, create a new Transaction Route variant |
| Hard to trace which pattern a transaction was supposed to follow | Every transaction stores its route ID — straightforward to audit |
Prerequisites
Both scenarios assume a Midaz environment with the following structure already in place:
| Entity | Alias | Type | Purpose |
|---|---|---|---|
| Alice’s account | @alice_checking | checking | Sender — Alice’s main checking account |
| Bob’s account | @bob_checking | checking | Receiver — Bob’s main checking account |
| BRL asset | — | — | Brazilian Real, registered as the operating asset |
Values in Midaz are represented in the smallest unit of the currency. For BRL,
15000 means R$ 150.00 (centavos).Scenario 1: Simple Pix transfer
Alice sends R$ 150.00 to Bob via Pix. The money moves from one checking account to another — no fees, no splits, just a clean peer-to-peer transfer.
The goal
- Debit Alice’s checking account by R$ 150.00
- Credit Bob’s checking account by R$ 150.00
- Validate that both accounts are of type
checkingbefore processing - Make this pattern reusable for every Pix transfer between checking accounts
Setting up the routes
Create the source Operation Route
This route defines the debit side of the transfer. The Save the returned
account_type rule means any account of type checking is valid as a source — the route doesn’t hardcode a specific sender.id — you’ll need it when building the Transaction Route.Create the destination Operation Route
This route defines the credit side. Same rule type: any
checking account qualifies as a valid receiver.Executing a Pix transfer
With the route in place, every Pix transfer references the Transaction Route ID. Midaz validates that the accounts match the route’s rules before processing.What happens under the hood
Midaz receives the transaction
The request includes the Transaction Route ID in the
route field. Midaz loads the route configuration.Source validation
For each
from entry, Midaz checks the account against the source Operation Route rules. Alice’s account is type checking — matches the account_type rule. Validation passes.Destination validation
For each
to entry, Midaz checks the account against the destination Operation Route rules. Bob’s account is type checking — validation passes.Scenario 2: Pix transfer with fee collection
Same flow as Scenario 1, but now the bank charges a R$ 1.50 fee on each Pix transfer. This adds a third Operation Route for the fee destination, and Alice’s total debit increases to R$ 151.50.
What changes
You already have the source and destination Operation Routes from Scenario 1. You need one additional Operation Route for the fee and a new Transaction Route that groups all three.| Entity | Alias | Type | Purpose |
|---|---|---|---|
| Fee revenue account | @revenue_pix_fees | revenue | Internal account that collects Pix transfer fees |
Setting up the fee route
Create the fee Operation Route
Unlike the previous routes that use
account_type, this one uses the alias rule type. That means it targets a specific account — @revenue_pix_fees — and no other account can be used.Executing a Pix transfer with fee
Alice sends R$ 150.00 to Bob. The bank collects R$ 1.50. Alice’s total debit is R$ 151.50.What this unlocks
- Transparent fee collection — the fee is a first-class ledger entry, not hidden metadata. Finance and compliance teams see exactly where the R$ 1.50 went.
- Reusable building blocks — the source and destination Operation Routes are shared between the simple and fee variants. You only add what changes.
- Route-level control — your system can offer both “PIX Transfer” and “PIX Transfer with Fee” as distinct products, each backed by its own Transaction Route.
- Easy evolution — need a percentage-based fee? A split across multiple revenue accounts? Add new Operation Routes and compose a new Transaction Route. Existing flows remain untouched.
Understanding rule types
The two rule types serve different purposes. Choosing the right one depends on whether the account in a route should be dynamic or fixed.
| Rule type | validIf format | Behavior | When to use |
|---|---|---|---|
account_type | Array of strings — e.g., ["checking"] or ["checking", "savings"] | Accepts any account that matches one of the specified types | Dynamic participants — the sender or receiver can be any account of that type |
alias | String — e.g., "@revenue_pix_fees" | Must target a specific account by its alias | Fixed participants — the route always hits the same account, like a fee or settlement account |
What you need to get started
| Requirement | Details |
|---|---|
| Midaz (v3.x.x+) | Core ledger with Transaction Route validation enabled |
| Route validation config | Set TRANSACTION_ROUTE_VALIDATION in the Transaction service .env to include your organization_id:ledger_id |
| Accounts and asset | At minimum: two customer accounts and a BRL asset registered in the ledger |
| Operation Routes | One per operation leg (source, destination, fee) |
| Transaction Route | Groups the Operation Routes into a reusable pattern |
Transaction Route validation must be explicitly enabled per ledger. See Working with Transaction Routing for the configuration steps.
Next steps
Transaction Routing
Understand how Operation Routes and Transaction Routes work at a deeper level.
Transactions
Learn about Midaz’s double-entry transaction model and N:N capabilities.
Pix with automated fees
Combine the Pix Plugin with the Fees Engine for automated fee management.
Pix Plugin overview
Explore the full Pix Plugin architecture and connection models.