Accounting Entries

Map transaction actions and route directions to accounting classifications, and annotate every operation with its accounting code and description.

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).
• A set of action mappings — one entry per action type, each with its own debit and/or credit rubric.

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; when 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 8 action types

---

Each action represents a distinct transactional event. The first five actions cover the transaction lifecycle. The last three cover overdraft, block, and unblock movements. A single rubric can map different debit and credit classifications for each action. Every stage of an operation then receives the right accounting annotation.

Action	Identifier	Description
Direct	direct	Immediate, single-step debit/credit between two accounts, with no intermediate stages (e.g., a fee or adjustment).
Hold	hold	Reserves funds by creating a pending movement (moves value from available to on_hold on the source account).
Commit	commit	Confirms a previously held amount, releasing the on_hold value to the destination account.
Cancel	cancel	Cancels/reverses a hold, returning the on_hold value to the available balance on the source account.
Revert	revert	Reverses a completed direct 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.

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 them, 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 accounting classifications within the same rubric. 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

{
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — outbound"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — inbound"
            }
        },
        "hold": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — reserve"
            },
            "credit": {
                "code": "2.1.1.001",
                "description": "Pending settlement — hold"
            }
        }
    }
}

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, a requested action with no routes in the transaction-route cache returns 0157 ErrNoRoutesForAction. 0117 ErrAccountingRouteNotFound applies when an operation route ID is absent from that cache.

PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings

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

In strict mode, do not treat 0117 ErrAccountingRouteNotFound as the error for every unmapped action: it applies when an operation route ID is absent from the transaction-route cache. A requested action with no routes in that cache returns 0157 ErrNoRoutesForAction.

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.