Midaz with Pix Transaction Routes

Every Pix transaction follows a pattern: debit the sender, credit the receiver, and sometimes collect a fee. When that pattern lives only in application code, every team that touches Pix re-implements the same validation logic. Each implementation is another chance for inconsistency. Transaction Routes move that pattern into the ledger. You define the rules once, and Midaz enforces them on every transaction. The result is a single source of truth for how Pix money flows through your system. This page walks through two scenarios — a simple peer-to-peer transfer and a transfer with a fee. Each scenario shows how to set up the routes and what your team gains from them.

Why this matters

For product and operations teams, Transaction Routes give you auditable Pix flows without application-level enforcement. Every transaction carries a reference to the route it followed, so compliance reviews and incident investigations stay simple. For engineering teams, routes remove repetitive validation code. You configure the account and fee rules once. Midaz then enforces them at the ledger level on every Pix integration.

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

For a deeper look at how Transaction Routes and Operation Routes work, see Accounting Routes.

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 decimal amounts. For BRL, 150.00 means R$ 150.00.

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 checking before 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 account_type rule accepts any account of type checking as a source. The route does not hardcode a specific sender.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes

{
  "title": "Pix - Debit Sender",
  "description": "Debits the sender's checking account in a Pix transfer",
  "code": "PIX-SEND-SRC",
  "operationType": "source",
  "account": {
    "ruleType": "account_type",
    "validIf": ["checking"]
  },
  "metadata": {
    "payment_method": "pix",
    "direction": "outbound"
  }
}

Save the returned id — you need it when you build the Transaction Route.

Create the destination Operation Route

This route defines the credit side. It uses the same rule type: any checking account qualifies as a valid receiver.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes

{
  "title": "Pix - Credit Receiver",
  "description": "Credits the receiver's checking account in a Pix transfer",
  "code": "PIX-SEND-DST",
  "operationType": "destination",
  "account": {
    "ruleType": "account_type",
    "validIf": ["checking"]
  },
  "metadata": {
    "payment_method": "pix",
    "direction": "inbound"
  }
}

Create the Transaction Route

Group both Operation Routes into a single Transaction Route. This route represents “Pix Transfer” in your system.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes

{
  "title": "Pix Transfer",
  "description": "Standard Pix transfer between two checking accounts",
  "operationRoutes": [
    "<pix-send-src-id>",
    "<pix-send-dst-id>"
  ],
  "metadata": {
    "payment_rail": "pix",
    "spi_message_type": "pacs.008",
    "regulation": "BCB_PIX"
  }
}

Replace the placeholder IDs with the actual Operation Route IDs from the previous steps.

Executing a Pix transfer

With the route in place, every Pix transfer references the Transaction Route ID in the routeId field. Midaz validates that the accounts match the route’s rules before it processes the transaction.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json

{
  "chartOfAccountsGroupName": "PIX",
  "description": "Pix transfer from Alice to Bob",
  "code": "PIX-20260306-001",
  "routeId": "<pix-transfer-route-id>",
  "send": {
    "asset": "BRL",
    "value": "150.00",
    "source": {
      "from": [
        {
          "accountAlias": "@alice_checking",
          "amount": { "asset": "BRL", "value": "150.00" },
          "description": "Pix sent to Bob",
          "routeId": "<pix-send-src-id>"
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@bob_checking",
          "amount": { "asset": "BRL", "value": "150.00" },
          "description": "Pix received from Alice",
          "routeId": "<pix-send-dst-id>"
        }
      ]
    }
  },
  "metadata": {
    "pix_end_to_end_id": "E123456782026030614300000000001",
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00"
  }
}

What happens under the hood

Midaz receives the transaction

The request carries the Transaction Route ID in the routeId 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, so it 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, so validation passes.

Midaz processes the transaction

Both validations pass, so Midaz creates the transaction atomically. It debits @alice_checking by R$ 150.00 and credits @bob_checking by R$ 150.00.

If Alice sends from a savings account instead, Midaz rejects the transaction. The route accepts only checking accounts as sources, and you write no application-side validation.

Scenario 2: Pix transfer with fee collection

This flow matches Scenario 1, but now the bank charges a R$ 1.50 fee on each Pix transfer. The flow adds a third Operation Route for the fee destination, and Alice’s total debit rises to R$ 151.50.

What changes

You already have the source and destination Operation Routes from Scenario 1. You add one 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

The previous routes use account_type. This one uses the alias rule type instead. It targets one specific account — @revenue_pix_fees — and no other account qualifies.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes

{
  "title": "Pix - Fee Collection",
  "description": "Credits the bank's revenue account with the Pix transfer fee",
  "code": "PIX-FEE-DST",
  "operationType": "destination",
  "account": {
    "ruleType": "alias",
    "validIf": "@revenue_pix_fees"
  },
  "metadata": {
    "fee_type": "pix_transfer_fee"
  }
}

Create the Transaction Route with fee

This route groups the original source and destination routes with the new fee route. It is a separate Transaction Route from the simple transfer, so your system can offer both variants.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes

{
  "title": "Pix Transfer with Fee",
  "description": "Pix transfer between checking accounts with fee collection",
  "operationRoutes": [
    "<pix-send-src-id>",
    "<pix-send-dst-id>",
    "<pix-fee-dst-id>"
  ],
  "metadata": {
    "payment_rail": "pix",
    "includes_fee": true
  }
}

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.

POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json

{
  "chartOfAccountsGroupName": "PIX",
  "description": "Pix transfer from Alice to Bob (with fee)",
  "code": "PIX-20260306-002",
  "routeId": "<pix-transfer-with-fee-route-id>",
  "send": {
    "asset": "BRL",
    "value": "151.50",
    "source": {
      "from": [
        {
          "accountAlias": "@alice_checking",
          "amount": { "asset": "BRL", "value": "151.50" },
          "description": "Pix sent to Bob + transfer fee",
          "routeId": "<pix-send-src-id>"
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@bob_checking",
          "amount": { "asset": "BRL", "value": "150.00" },
          "description": "Pix received from Alice",
          "routeId": "<pix-send-dst-id>"
        },
        {
          "accountAlias": "@revenue_pix_fees",
          "amount": { "asset": "BRL", "value": "1.50" },
          "description": "Pix transfer fee",
          "routeId": "<pix-fee-dst-id>"
        }
      ]
    }
  },
  "metadata": {
    "pix_end_to_end_id": "E123456782026030614300000000002",
    "fee_amount": "1.50"
  }
}

Result: Midaz debits Alice R$ 151.50. Bob receives R$ 150.00. The bank collects R$ 1.50. All in a single atomic transaction — fully balanced, fully auditable.

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 simple and fee variants share the source and destination Operation Routes. You add only 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 — to add a percentage-based fee or a split across revenue accounts, create new Operation Routes and compose a new Transaction Route. Existing flows stay untouched.

Understanding rule types

The two rule types serve different purposes. The right choice depends on whether the account in a route is 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

You can combine both rule types within a single Transaction Route. Scenario 2 does exactly that: account_type for the dynamic sender and receiver, alias for the fixed fee account.

What you need to get started

Requirement	Details
Midaz (v3.x.x+)	Core ledger with Transaction Route validation enabled
Route validation config	Enable route validation via the Ledger Settings API: `PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings` with `{"accounting": {"validateRoutes": true}}`
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

You must enable Transaction Route validation for each ledger. See Working with Accounting Routes for the configuration steps.

Next steps

Accounting Routes

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 Switch

Explore the full Pix Plugin architecture and connection models.

Overview

Direct via JD

Indirect via BTG

Midaz with Pix Transaction Routes

Why this matters

Prerequisites

Scenario 1: Simple Pix transfer

The goal

Setting up the routes

Executing a Pix transfer

What happens under the hood

Scenario 2: Pix transfer with fee collection

What changes

Setting up the fee route

Executing a Pix transfer with fee

What this unlocks

Understanding rule types

What you need to get started

Next steps

Accounting Routes

Transactions

Pix with automated fees

Pix Switch

​Why this matters

​Prerequisites

​Scenario 1: Simple Pix transfer

​The goal

​Setting up the routes

​Executing a Pix transfer

​What happens under the hood

​Scenario 2: Pix transfer with fee collection

​What changes

​Setting up the fee route

​Executing a Pix transfer with fee

​What this unlocks

​Understanding rule types

​What you need to get started

​Next steps

Accounting Routes

Transactions

Pix with automated fees

Pix Switch

Why this matters

Prerequisites

Scenario 1: Simple Pix transfer

The goal

Setting up the routes

Executing a Pix transfer

What happens under the hood

Scenario 2: Pix transfer with fee collection

What changes

Setting up the fee route

Executing a Pix transfer with fee

What this unlocks

Understanding rule types

What you need to get started

Next steps