Accounting Routes

Accounting Routes are Midaz’s two-layer validation system for financial transactions, built from Accounting Routes (which define the full transaction pattern) and Operation Routes (which validate each individual operation within that pattern). Together, they ensure every transaction is both structurally correct and compliant with your business rules.

Naming: This concept is called Accounting Routes in the Lerian Console and product documentation. In the API and SDKs the transaction-level route is represented by the transactionRoute resource (and transaction-route endpoints). The two terms refer to the same thing.

Accounting Routes define the complete structure of a transaction — the required sequence of operations and how they fit together to form a valid financial event.
Operation Routes define the rules for each individual operation (or “leg”) of that transaction, including the expected account type or specific account, the accounting annotation, and whether it’s a debit or credit.

When a transaction is submitted, Midaz validates it in two layers: Accounting Routes ensure the overall structure matches the predefined pattern, while Operation Routes confirm that each component meets account requirements and business rules. If any part of the transaction fails these checks, it’s rejected before it can be recorded — protecting the integrity of your ledger without limiting its flexibility.

You define the validation patterns through Operation Routes and Accounting Routes. Midaz ensures your transactions comply with these rules before processing.

What are Accounting Routes for?

Accounting Routes provide structured control over your financial operations by separating transaction logic from business code. Instead of hardcoding validation rules in your application, you configure reusable patterns that ensure every financial movement follows your organization’s requirements. These entities are dedicated to linking Transactions and Operations from the Midaz ledger to higher-level abstractions that facilitate integration with specialized plugins and external systems, especially for accounting and treasury abstractions. The structured annotations and classifications create a standardized vocabulary that other components can understand and leverage. This approach delivers:

Consistency: All transactions follow predefined structures regardless of where they originate.
Flexibility: Adapt your ledger design to match your business needs without code changes.
Integrity: Automatic validation prevents malformed transactions from affecting your ledger.
Maintainability: Centralized configuration makes it easier to update financial rules as your business evolves.
Interoperability: Business-semantic fields enable seamless integration with accounting plugins and external financial systems.

Whether you’re processing simple transfers or complex multi-party transactions, Accounting Routes ensure your financial data remains structured, validated, and reliable at scale while providing the semantic foundation for advanced integrations.

Working with Accounting Routes

To use Accounting Routes, you must complete the initial configuration followed by ongoing transaction execution. Here’s your step-by-step process:

Initial Setup

1. Configure Ledger for transaction route validation

To activate transaction route validation for a specific Ledger, enable the validation settings through the Ledger Settings API. This controls whether transactions in that Ledger must comply with your configured routes.

{
  "accounting": {
    "validateRoutes": true,
    "validateAccountType": true
  }
}

validateRoutes: When enabled, every transaction must reference a valid transaction route.
validateAccountType: When enabled, account types are validated against operation route rules.

Settings changes take effect immediately — no redeployment required. You can update them at any time via the API.

2. Create Operation Routes

Create Operation Routes that define validation rules and behavior for individual transaction components. Key fields:

title: Brief label that identifies the operation route.
code (deprecated): a legacy external reference kept for backward compatibility. It is not written to operations — the engine records the resolved rubric’s code (from accountingEntries) as routeCode on each operation instead.
description: Optional detailed explanation.
metadata: Key-value pairs for business context and custom categorization.
operationType: The accounting direction for this route — source, destination, or bidirectional.
- source — Identifies accounts where funds originate (debit side).
- destination — Identifies accounts where funds are sent (credit side).
- bidirectional — Applies to both sides of the transaction, acting as both source and destination.
account: Optional validation rules specifying required account type or specific account.
- ruleType: Type of account validation rule (account_type, alias).
- validIf: The expected value that must match for validation to pass.
accountingEntries: Optional accounting entries for each action type. See Accounting Entries below.

Configure account rules based on your needs: Option A: No Account Rule If you don’t need account validation for the operation route, omit the account object:

 {
    "title": "Fee Collection",
    "description": "Operation route for collecting service fees from user transactions",
    "metadata": {
        "businessUnit": "payments",
        "category": "revenue"
    },
    "operationType": "source"
}

Option B: Account Validation Rule If you need account validation for the operation, configure account rules based on your ledger setup:

Target Specific Account

Validate against a specific account using its alias.

{
    "title": "Fee Revenue Collection",
    "description": "Operation route for crediting collected fees to revenue account",
    "metadata": {
        "businessUnit": "payments",
        "category": "revenue"
    },
    "operationType": "destination",
    "account": {
        "ruleType": "alias",
        "validIf": "@external/BRL"
    }
}

Target Account Type

Validate against specific account types.

{
    "title": "User Cashout Fee",
    "description": "Operation route for collecting fees from user cashout transactions",
    "metadata": {
        "businessUnit": "payments",
        "category": "fee"
    },
    "operationType": "source",
    "account": {
        "ruleType": "account_type",
        "validIf": ["user_wallet", "asset"]
    }
}

Option C: With Accounting Entries Attach accounting entries directly to the operation route through the accountingEntries field, mapping each transaction-lifecycle stage to the correct double-entry accounting codes. The full action-type model, debit/credit requirements, and validation matrix are covered in Configure Accounting Entries (Actions) below. A route with accounting entries configured:

{
    "title": "Pix Cash-in - Current Account",
    "description": "Operation route for receiving Pix payments into current account",
    "operationType": "source",
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.001",
                "description": "Cash - Available funds"
            },
            "credit": {
                "code": "3.1.001",
                "description": "Service Revenue"
            }
        },
        "hold": {
            "debit": {
                "code": "1.1.002",
                "description": "Clearing Values"
            },
            "credit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            }
        }
    },
    "account": {
        "ruleType": "alias",
        "validIf": "@current_account"
    },
    "metadata": {
        "channel": "pix"
    }
}

The operationType field also supports bidirectional, which allows the route to operate in both directions — useful for routes that handle both sending and receiving, or for operations that may need to be reversed.

3. Build Accounting Routes

Complete your setup by combining Operation Routes into Accounting Routes (the transactionRoute resource in the API). These define your complete transaction patterns, mapping how different operations work together to form balanced financial events that match your business processes.

The operationRoutes field uses an array of objects with operationRouteId rather than a plain array of UUID strings.

{
    "title": "Fee Transaction",
    "description": "Complete transaction for collecting fees from user cashout operations",
    "metadata": {
        "transactionType": "cashout_fee",
        "businessFlow": "withdrawal_processing"
    },
    "operationRoutes": [
        {
            "operationRouteId": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
        },
        {
            "operationRouteId": "0197e675-37cc-71d7-96c2-f58000f33aa0"
        }
    ]
}

4. Configure Accounting Entries (Actions)

Each Operation Route can include Accounting Entries — structured rubrics that define how debit and credit entries are recorded for each type of transactional event (direct, hold, commit, cancel, revert). They are what the engine uses to resolve which accounts get debited and credited for each action, and they determine the routeCode/routeDescription annotations written on each operation. Whether a missing rubric is tolerated (graceful) or rejected with 0117 ErrAccountingRouteNotFound (strict) is controlled by accounting.validateRoutes in the Ledger Settings.

The accounting-entry actions, the debit/credit requirements per operation type, the graceful vs. strict validation modes, and full configuration examples are documented in detail on the Accounting Entries page. This section covers only how rubrics attach to Operation Routes.

At the route level, accounting entries are supplied through the accountingEntries block (see Option C under Create Operation Routes above), with one entry per action and a debit and/or credit rubric depending on the route’s operationType:

Source routes require the debit rubric.
Destination routes require the credit rubric.
Bidirectional routes require both debit and credit rubrics.

Accounting entries validation matrix

Not every combination of operationType and action is valid. Midaz enforces a strict validation matrix when you create or update an Operation Route — if the rules aren’t met, the request is rejected before persisting. Understanding this matrix is critical for integrators: sending an invalid combination returns error 0166 (field required) or 0162/0165 (scenario not allowed for direction). source

Action	Debit	Credit	Notes
`direct`	Required	Optional	Standard one-step transaction at origin
`hold`	Required	Required	Reserves funds — moves available → on_hold
`commit`	Required	Optional	Finalizes a two-phase transaction
`cancel`	Required	Required	Releases reserved funds — moves on_hold → available
`revert`	—	—	Not allowed (error `0165`). Use `bidirectional` instead

destination

Action	Debit	Credit	Notes
`direct`	Optional	Required	Standard one-step transaction at destination
`hold`	—	—	Not allowed (error `0162`)
`commit`	Optional	Required	Finalizes a two-phase transaction
`cancel`	—	—	Not allowed (error `0162`)
`revert`	—	—	Not allowed (error `0165`). Use `bidirectional` instead

bidirectional

Action	Debit	Credit	Notes
`direct`	Required	Required	Both sides of the double entry
`hold`	Required	Required	Both sides of the double entry
`commit`	Required	Required	Both sides of the double entry
`cancel`	Required	Required	Both sides of the double entry
`revert`	Required	Required	Only direction that supports revert

An entry with neither debit nor credit is always rejected, regardless of operation type or action.

Additional rules:

Reserve group atomicity: If you define hold, you must also define commit and cancel (and vice versa). These three actions form an atomic group — you can’t configure one without the others.
Direct is mandatory: If any other action (hold, commit, cancel, revert) is defined, direct must also be present. It serves as the baseline entry for the operation route.

When designing your operation routes, start with the direct action and add hold/commit/cancel only if you need two-phase transaction support. Add revert only on bidirectional routes.

Ongoing Operations

5. Execute Validated Transactions

With your routing configuration in place, you can now submit transactions with confidence by including the ID of the previously created Accounting Route in your transaction request. Midaz will automatically validate the transaction against your defined routing patterns, ensuring consistency and integrity across all financial operations. For the previously configured Accounting Route and Operation Routes examples, the system composes the following validation structure:

Transaction Route: "Fee Transaction" (ID: 5656daa5-5b2a-4637-955f-e43bafceaf5d)

├── Operation Route 1: "User Cashout Fee" (ID: 0197e6aa-1695-734a-a8c3-8c79e0ad32c2)
│   ├── Type: source
│   ├── Account Rule: account_type ["user\_wallet", "asset"]
│   └── Validates: source operations in transactions
└── Operation Route 2: "Fee Revenue Collection" (ID: 0197e675-37cc-71d7-96c2-f58000f33aa0)
    ├── Type: destination
    ├── Account Rule: alias "@external/BRL"
    └── Validates: destination operations in transactions

For route properties on Midaz transactions, an appropriate payload request:

{
    "route": "5656daa5-5b2a-4637-955f-e43bafceaf5d",
    "description": "Cashout fee collection transaction",
    "send": {
        "asset": "BRL",
        "value": "10",
        "source": {
            "from": [
                {
                    "accountAlias": "@user/wallet_123",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Fee debit from user wallet",
                    "route": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
                }
            ]
        },
        "distribute": {
            "to": [
                {
                    "accountAlias": "@external/BRL",
                    "amount": {
                        "asset": "BRL",
                        "value": "10"
                    },
                    "description": "Fee credit to revenue account",
                    "route": "0197e675-37cc-71d7-96c2-f58000f33aa0"
                }
            ]
        }
    }
}

When this transaction is submitted, Midaz validates that the @user/wallet_123 account matches the user_wallet account type rule, and @external/BRL matches the exact alias requirement, ensuring the transaction follows your configured routing patterns.

Route fields on operations

When route validation is enabled and accounting entries are configured, every successfully processed operation will include two additional fields populated from the matched rubric:

routeCode — The code of the resolved AccountingRubric for that operation’s action and direction.
routeDescription — The description of the resolved accounting rubric, populated alongside routeCode.

These fields provide a direct link between each operation and its accounting classification, enabling downstream systems (such as Reporter) to produce accurate financial reports without additional lookups.

Managing Operation and Accounting Routes

To configure your Operation Routes, use the following endpoints:

Create an Operation Route — Define a new accounting rule for your operations.
List Operation Routes — View all configured Operation Routes.
Retrieve an Operation Route — Get detailed information on a specific Operation Route.
Update an Operation Route — Modify existing accounting rules.
Delete an Operation Route — Remove an outdated or unused Operation Route.

To configure your Accounting Routes (the transactionRoute resource in the API), use the following endpoints:

Create a Transaction Route — Define new routing logic to connect transactions to accounting operations.
List Transaction Routes — View all configured Transaction Routes.
Retrieve a Transaction Route — Get details of a specific Transaction Route.
Update a Transaction Route — Modify existing routing criteria.
Delete a Transaction Route — Remove routes that are no longer applicable.

Midaz Core

CRM

Fees

Accounting Routes

What are Accounting Routes for?

Working with Accounting Routes

Initial Setup

1. Configure Ledger for transaction route validation

2. Create Operation Routes

3. Build Accounting Routes

4. Configure Accounting Entries (Actions)

Accounting entries validation matrix

Ongoing Operations

5. Execute Validated Transactions

Route fields on operations

Managing Operation and Accounting Routes

​What are Accounting Routes for?

​Working with Accounting Routes

​Initial Setup

​1. Configure Ledger for transaction route validation

​2. Create Operation Routes

​3. Build Accounting Routes

​4. Configure Accounting Entries (Actions)

Accounting entries validation matrix

​Ongoing Operations

​5. Execute Validated Transactions

Route fields on operations

​Managing Operation and Accounting Routes

What are Accounting Routes for?

Working with Accounting Routes

Initial Setup

1. Configure Ledger for transaction route validation

2. Create Operation Routes

3. Build Accounting Routes

4. Configure Accounting Entries (Actions)

Ongoing Operations

5. Execute Validated Transactions

Managing Operation and Accounting Routes