Accounting Entries

Accounting Entries (also known as Rubricas) map a transaction action to the ledger entries it generates. The engine uses this map to resolve which accounts to debit and credit for each action. It then annotates each operation with the correct double-entry accounting codes at every stage of the transaction lifecycle.

What are Accounting Entries

A rubric maps a transaction action to the ledger accounts the engine must debit and credit. Instead of computing each classification by hand, you register rubrics once. Midaz then resolves them automatically as it processes transactions. Each rubric carries:

code — a unique identifier (the chart of accounts code, e.g., 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, 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. Source routes require the debit rubric. Destination routes require the credit rubric. Bidirectional routes 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 accounts for each action. Every stage of an operation then lands on the right ledger entry.

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`	Classifies a fund-block movement that freezes value on an account (for example, an `asset-freeze`).
Unblock	`unblock`	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. Block and unblock classify operations that the dedicated block and unblock transaction endpoints produce. You register the rubrics for all three the same way as the other actions.

Each action can point to different debit and credit account mappings 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": {
        "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, the transaction proceeds normally when no rubric matches an action. Midaz leaves the routeCode and routeDescription fields empty (nil) for that operation. It raises no error.

Strict (opt-in)

Set accounting.validateRoutes to true in the Ledger Settings to require a registered rubric for every action. Midaz then rejects any operation whose action and direction has no registered mapping. It returns error 0117 ErrAccountingRouteNotFound.

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

In strict mode, if a route has accounting entries but a transaction uses an unmapped action, Midaz denies the transaction with 0117 ErrAccountingRouteNotFound. A Two-Phase Transaction triggers this when you map only direct. This gate keeps every stage of an operation mapped before execution, so your accounting reports stay consistent.

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

Configuring Accounting Entries

Validation modes

Default (graceful)

Strict (opt-in)

​What are Accounting Entries

​The 8 action types

​Configuring Accounting Entries

​Validation modes

​Default (graceful)

​Strict (opt-in)

What are Accounting Entries

The 8 action types

Configuring Accounting Entries

Validation modes

Default (graceful)

Strict (opt-in)