Accounting Entries

Accounting Entries (also known as Rubricas) map a transaction action and route direction to an accounting code and description. They annotate an operation after route resolution. Operation Route rules and transaction legs determine the participating accounts.

What are Accounting Entries

A rubric maps a transaction action and route direction to an accounting classification. Instead of computing each classification by hand, you register rubrics once. Midaz then resolves them automatically as it processes transactions. Each rubric carries:

code: an accounting code (for example, 1.1.1.001).
description: a human-readable label for the entry (e.g., Customer checking — outbound).

When the engine processes a transaction with route validation (accounting.validateRoutes) enabled and a matching rubric registered, it resolves the rubric for each operation. It records the resulting routeCode and routeDescription on the operation. This gives you a complete audit trail from transaction to operation to rubric. Your teams can trace exactly which accounting rule applied to each movement.

Configure rubrics per action on each Operation Route. For direct and commit actions, Source routes require the debit rubric and Destination routes require the credit rubric. Dedicated block and unblock rubrics are optional. If they are absent, Midaz resolves the direct rubric for those actions. Source-side hold and cancel actions require both rubrics, and overdraft requires both on every supported route type. Bidirectional routes always require both.

The 9 action types

Each action is a distinct transactional event. The first five actions cover the transaction lifecycle. The next three cover overdraft, block, and unblock movements. The last one covers transactions that span Ledgers. An Operation Route can map different debit and credit rubrics for each action. Every stage of an operation then receives the right accounting annotation. The Hold and Cancel rows show a balance with direction: credit. On a direction: debit balance, a hold increases available and a cancel decreases it. onHold moves the same way on both.

Action	Identifier	Description
Direct	`direct`	Immediate, single-step debit/credit with no intermediate stages (e.g., a fee or adjustment).
Hold	`hold`	Reserves funds by creating a pending movement (moves value from `available` to `onHold` on the source account).
Commit	`commit`	Confirms a previously held amount, releasing the `onHold` value to the destination account.
Cancel	`cancel`	Cancels/reverses a hold, returning the `onHold` value to the `available` balance on the source account.
Revert	`revert`	Reverses an `APPROVED` transaction by creating a counter-transaction that undoes the original.
Overdraft	`overdraft`	Classifies overdraft movements — the debit rubric marks overdraft usage (the deficit grows) and the credit rubric marks repayment (the deficit shrinks). Both rubrics are required when this entry is configured.
Block	`block`	Optionally classifies a fund-block movement that freezes value on an account (for example, an `asset-freeze`).
Unblock	`unblock`	Optionally classifies the release of previously blocked funds back to the `available` balance.
Cross-ledger	`crossLedger`	Classifies the External Account legs that Midaz adds when a transaction spans Ledgers. The debit rubric marks value that arrives from another Ledger. The credit rubric marks value that leaves to another Ledger. Both rubrics are required.

Overdraft classifies companion operations that the engine generates automatically during overdraft usage and repayment. For every supported route type and direction, configure both the debit and credit rubrics. Block and unblock can use dedicated rubrics for operations that the block and unblock transaction endpoints produce. Without those rubrics, those actions use the direct rubric. When needed, register dedicated rubrics for these actions in the same way as for the other actions.

Each action can point to different debit and credit rubrics on the same Operation Route. Map only the actions a route uses. If you enable strict validation (below), cover every action your transactions emit.

Configuring Accounting Entries

You register rubrics through the API as part of your Operation Routes. The accountingEntries block on a route defines one entry per action. Each entry carries its debit and/or credit rubric:

{
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — outbound"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — inbound"
            }
        }
    }
}

You manage these entries through the Operation Route endpoints. See Create an Operation Route and Update an Operation Route. For the full configuration flow, refer to Transaction Routing.

Validation modes

Midaz reacts to a missing rubric based on the Ledger’s accounting settings. Two distinct gates control this behavior:

Default (graceful)

By default (accounting.validateRoutes disabled), Midaz does not resolve rubrics at all: the transaction proceeds normally and the routeCode and routeDescription fields stay empty (nil) for every operation. It raises no error.

Strict (opt-in)

Set accounting.validateRoutes to true in the Ledger Settings to enforce route validation. In strict mode, Midaz returns 0157 when no Operation Route of the Transaction Route has an entry for the requested action. It returns 0117 when a leg names no Operation Route, or one that the Transaction Route does not provide for that action. An overdraft movement on a route without an overdraft entry returns 0492.

{
  "accounting": {
    "validateRoutes": true
  }
}

Use strict mode in production ledgers where every transaction type needs an accounting classification. The graceful default helps while you onboard routes. In production, it can silently leave movements without a classification.

When Midaz finds a matching rubric, it annotates the operation with two fields:

routeCode: the code of the resolved AccountingRubric for that action and direction.
routeDescription: the description of the resolved rubric, populated alongside routeCode.

Midaz Core

CRM

Fees

Accounting Entries

What are Accounting Entries

The 9 action types

Configuring Accounting Entries

Validation modes

Default (graceful)

Strict (opt-in)

​What are Accounting Entries

​The 9 action types

​Configuring Accounting Entries

​Validation modes

​Default (graceful)

​Strict (opt-in)

What are Accounting Entries

The 9 action types

Configuring Accounting Entries

Validation modes

Default (graceful)

Strict (opt-in)