Operation Routes and Transaction Routes work together to provide structured validation for financial transactions in Midaz, ensuring consistency and integrity across your ledger design.

An Operation Route defines the validation rules for individual transaction components (each "leg" of a financial transaction), specifying the accounting annotation, expected account type or specific account, and direction (debit/credit). A Transaction Route maps transactional events of each operation from the structure into complete transaction patterns that ensure proper validation and processing.

When you submit a transaction, Midaz validates your data against these configured patterns: Transaction Routes ensure your complete transaction follows predefined structures, while Operation Routes validate each individual component meets account requirements and business rules.

This validation layer maintains consistency, structure, and integrity across all financial movements while providing flexibility in your ledger design. If submitted data doesn't match the configured validation rules, the transaction is rejected to preserve data integrity.

📘

Note

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

What is Transaction Routing for?

Transaction Routing Entities 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 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, Transaction Routing Entities ensure your financial data remains structured, validated, and reliable at scale while providing the semantic foundation for advanced integrations.

How it works

To use Transaction Routing, users must complete initial configuration followed by ongoing transaction execution. Here's your step-by-step process:

Initial Setup

1. Configure Ledger for Transaction Route Validation

In case you want to activate transaction route validation to a specific ledger, you must configure it in the Transaction service. This means updating the Transaction variables in the .env file of Midaz Transaction service where you want to use route validation.

Your configuration should look like this:

# List of <organization-id>:<ledger-id> separated by comma
TRANSACTION_ROUTE_VALIDATION=

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.
• description: Optional detailed explanation.
• metadata: Key-value pairs for business context and custom categorization.
• operationType: source or destination indicating the operation's directional flow.
• 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.

Configure them 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"]
    }
}

3. Build Transaction Routes

Complete your setup by combining Operation Routes into Transaction Routes. These define your complete transaction patterns, mapping how different operations work together to form balanced financial events that match your business processes.

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

Ongoing Operations

4. Execute Validated Transactions

With your routing configuration in place, you can now submit transactions with confidence by including the ID of the previously created Transaction 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 Transaction 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.

Managing Operation and Transaction 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 Transaction Routes, 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.