Ledgers & Balance Management

The CoreBanq Ledger System is a high-performance, double-entry accounting engine. It serves as the "source of truth" for all financial positions, providing real-time balance tracking, hierarchical aggregation, and administrative holds.

Purpose and use

Ledgers record the bank's financial truth: customer money, bank money, fees, suspense, settlement, holds, and control balances. Every balance-affecting operation should be explainable from ledger entries and their roll-up into the chart of accounts.

Who uses this. Finance controllers, operations staff, reconciliation teams, auditors, treasury users, and support teams use ledgers to answer balance, posting, safeguarding, and audit questions. Regulatory reporting teams use the same subledger structure to prepare safeguarding figures, and product teams use it to decide where a new money flow should be booked.

How it works. Customer-facing accounts map to subledgers. Subledgers roll into control ledgers. Ledger entries debit and credit those ledgers, while holds adjust available balance without changing posted balance until settlement occurs.

What users do. Users review ledger hierarchy, inspect balances, place or release holds, post journal entries through controlled flows, and trace a transfer or fee back to its accounting entries.

Outcomes and side effects. Ledger postings update posted and local-currency balances, create audit evidence, and feed account balances, statements, reconciliation, and reporting. Holds affect spendable balance and must be released or settled through traceable operations.

See also:

• Reconciliation API
• Journal Transactions

Object Relationships

The system follows a strict hierarchical and relational model to ensure data integrity and auditability.

Hierarchy Breakdown

1. Control Ledgers: Represent categories in the Chart of Accounts (e.g., "Public Customer Deposits"). They aggregate balances from children but never hold individual customer funds directly — a control ledger that has any subledger under it stops accepting direct postings.
2. Subledgers: An account or a customer can own several subledgers, one per purpose (Current, Hold, Fees receivable, Interest accrual, Collateral) and currency — see Why one customer has several subledgers below. Every account still gets its Current subledger automatically at opening; the rest open lazily, the first time each is actually needed.
3. Customer Account: The user-facing entity. The account balance is a projection of its Current subledger specifically — the account never changes shape when a customer also picks up a Hold or Fees receivable subledger elsewhere.

Monetary Amount Format

All monetary amounts in API responses use the CcyAmtWithPrecision format. This self-describing format expresses amounts in minor/atomic units (e.g., cents for EUR, satoshi for BTC) as a string, alongside the currency code and precision.

{
  "amount": "123456",
  "currency": "EUR",
  "precision": 2
}

To convert to a display value: displayAmount = amount / 10^precision.

This format is used for all balance, amount, and monetary fields including: balance_posted, balance_available, balance_pending, balance_lcy, overdraft_limit, total_amount, amount, amount_lcy, debit, credit, etc.

Balance Management Concepts

CoreBanq distinguishes between different balance states to support complex banking operations like "authorized but not settled" payments and administrative freezes.

Balance Types

The available-balance formula above is canonical and normative. It has exactly one implementation, AvailableBalance in , and every sufficiency gate reads it through CheckSufficientFunds. Pending credits deliberately do not raise available: money that has not settled is not spendable.

balance_available is maintained by delta as entries and holds move. It is never assigned the posted balance outright — doing so would set available == posted and erase every active hold on the ledger. DeriveAvailableBalance recomputes it from the source rows, and the daily consistency scan (OPS job ledgers.balance_consistency_scan) compares the two and reports any divergence.

Overdraft

overdraft_enabled alone does not permit an unbounded debit. The spendable amount is available + overdraft_limit, and a debit beyond it is rejected with ledgers.insufficient_funds and HTTP 402.

When a ledger stops accepting postings

Two states close a ledger to new entries, and both are rejected with HTTP 409:

A closing_date in the future is a planned closure and does not block anything yet.

This applies to every path that posts to a ledger: the direct entry endpoint (POST /v1/ledgers/entries), journals, memo posts and holds. The direct entry endpoint is itself switchable: with ledgers.allow_legacy_direct_posting off it refuses every request with 400 ledgers.legacy_direct_posting_disabled and points at POST /v1/ledgers/journals. Transfers are checked at initiation, where all three ledgers — source, transit and destination — must be postable. Completion is deliberately not re-checked: it settles money that initiation already moved onto transit, so refusing it because the destination closed in between would strand the amount with every retry failing. See the transfers documentation.

A transfer moves the amount as it stands: nothing on this path converts it, so both ledgers must be in the same currency. A source and a destination denominated differently are refused at initiation with ledgers.currency_mismatch and HTTP 400 — before the source is debited — because the only way to settle such a pair here would be at an implied rate of 1.0. A ledger carrying no currency at all is refused with ledgers.transfer_currency_missing, which names both sides so the caller can see which one to fix. perform_conversion on the request is accepted and ignored; no conversion is implemented.

Which transit ledger the amount is parked on comes from configuration, one ledger code per ISO currency under ledgers.transit_ledgers.{CCY} — for example ledgers.transit_ledgers.CHF. The currency in the key is matched however either side spelled it: the ledger's stored code is trimmed and upper-cased, and a setting written in lower case is still honoured. That setting is read once, at initiation, and the resulting ledger is recorded on the transfer as transit_ledger_id, together with the amount's base-currency value, fixed at initiation from the source ledger's currency through the FX rates. Completion books that same value on the transit and destination ledgers, so the transit ledger's base-currency balance nets to zero over the two requests; a rate that moved in between is picked up by FX revaluation of the balances, not by the settlement. Completion settles off the recorded ledger rather than reading the setting again, so a setting that changes between the two requests cannot leave the parked amount behind on a ledger nothing will clear. A currency with no code configured is refused with currencies_m.missing_currency_info and HTTP 400, and a configured code naming no existing ledger with ledgers.ledger_not_found and HTTP 404. A configured transit ledger that is denominated in another currency, or carries none at all, is refused with ledgers.transit_ledger_currency_mismatch or ledgers.transit_ledger_currency_missing and HTTP 422 — both name the ledger and say the fault is the configuration rather than the request, because the caller chose neither.

The configured ledger also has to be denominated in the currency it is configured for. Nothing in the database enforces that, so it is checked before the amount is parked: a CHF transfer whose ledgers.transit_ledgers.CHF names a EUR ledger is refused with ledgers.transit_ledger_currency_mismatch and HTTP 422, naming the ledger and both currencies. That is a configuration defect rather than a bad request — the caller cannot correct it — and refusing at initiation is what keeps the amount from being parked where completion would then refuse to release it.

Field names

One name means one balance across every ledger endpoint. balance_current is the single legacy exception: it carries the posted balance in the balance-history response and is still emitted alongside balance_posted for existing consumers. New integrations should read balance_posted.

Balance Holds

Holds are administrative or system-driven restrictions on a ledger's available balance. Holds do not decrease the posted balance; they only reduce the spendable amount until they are released or expire.

Hold Scenarios:

• Card Authorizations: A merchant authorizes $50. A hold of $50 is placed.
• Administrative Hold: Compliance department freezes $10,000 pending verification.

Not implemented. Two capabilities were previously documented here that the service does not provide, and integrations must not be designed around them:

• Hold settlement. A hold cannot be converted into a debit entry. Release the hold and post the debit as two separate operations.
• Negative holds. A hold amount must be positive — enforced by the service and by a CHECK (amount > 0) constraint on ledgers.holds. Buying power cannot be raised with a negative hold; use overdraft_enabled and overdraft_limit.

Releasing a hold is idempotent: releasing one that is already released succeeds without restoring the balance a second time.

Balance Monitoring

Balance monitoring watches a control ledger's posted balance against a ladder of limits and raises an alert — or flags a suspension — the moment a posting carries the balance across one of them. The Audax configuration uses it for the licence-relevant figure: public customer deposits, which is control group 221 — Customer Deposits (Available) – Type A Customer (every Type A customer, every currency, rolled up in the base currency).

Who uses it. Compliance and risk officers receive the alerts; finance and operations read the same limits as lines on the deposit chart of the Admin UI home page and the Configurator dashboard.

How it works.

• The monitored ledgers and their limits are part of the ledgers configuration (balance_monitoring, one block per ledger code). Each rule has an order, a limit in minor units, a comparison (at or above / at or below), an action (alert or suspend) and the alert recipients and e-mail template.
• The check runs on every posting that touches a monitored ledger, including postings on a subledger that roll up into it. Rules are evaluated from the most severe order downwards; the first one the new balance satisfies is the level reached, and an alert is raised only when that posting is the one that crossed it — a balance that stays above a limit does not alert again on every further posting. The alert is queued together with the posting and sent right after the posting is booked, so a posting is never delayed or failed by the notification. Every rule must name its e-mail recipients; a rule without them, or with an unknown comparison, action or alert type, is rejected when the configuration is read.
• Customer deposits are a liability with a credit (positive) balance, so their rules read "at or above 75 000 000.00". A ledger that aggregates several currencies (221 sums CHF and EUR children) or is kept in a foreign currency is compared on its base-currency balance; a base-currency leaf on its own posted balance. The chart plots the same figure. Details in Balance monitoring.
• A changed limit applies within about thirty seconds on every instance, without a restart or re-seed. A configuration that cannot be read keeps the last good ladder; if there is none, monitoring is off and the error is logged until the configuration is fixed.

The Audax deposit ladder (all figures CHF, on ledger 221):

The same limits are returned with the ledger's balance-history chart (see the chart endpoint below), so every screen that plots the balance draws the ladder from one source.

Anatomy of a Ledger Account

A ledger account (a "ledger") is one account in the book of record — the thing postings land on and balances accumulate against. A ledger is either a control ledger (a chart-of-accounts line that aggregates, e.g. "Customer Deposits — Type A") or a subledger (one customer's or one account's own leaf that rolls up into a control). The attributes below give each ledger its identity, its money behaviour, its place in the hierarchy, and — for a subledger — what it belongs to. Several attributes have their own deep section already; those are cross-referenced rather than repeated.

Who reads these attributes. Finance sets up and maintains the chart of accounts; operations open and monitor subledgers; compliance and audit read the same attributes to understand what a ledger is and what it may hold.

Identity and nature

Balances and credit

The four balances and the overdraft facility each have their own section; the roles in brief:

Lifecycle and hierarchy

Accounting behaviour flags

Subledger anchoring (subledgers only)

A subledger is one customer's or one account's own leaf. These attributes say what it belongs to and what it is for; they are empty on a control ledger.

Record-keeping attributes (every ledger carries these)

Like every record, a ledger carries an identifier, created / modified timestamps and actors, and an active flag — all system-set, so every account and every change to it is attributable in the audit trail.

Anatomy of a Ledger Entry

A ledger entry is one posting line — a single debit or credit landed on one ledger. Entries are never booked alone: each one belongs to a transaction (a journal) whose lines must balance, debits equal to credits in every currency involved, so an entry is always one half of a larger, self-balancing movement (see Journal Transactions). Once posted, an entry is immutable — a mistake is corrected by a reversing entry, never by editing the original. Every field on an entry has a distinct functional role: some place it (which ledger, which journal), some carry the money (the amount, its base-currency equivalent, the running balance), some place it in time (booking timestamp versus value date), and some explain and govern it (event, description, status, metadata). This section describes each.

Who reads these fields. Finance and operations staff reconciling a ledger, compliance officers tracing a movement in an audit, and support staff answering a customer query all read the same entry — the field roles below are the shared vocabulary.

Placement — which ledger, which journal

The money — amount, base-currency equivalent, running balance

Every monetary figure on an entry is held in minor units (the smallest indivisible unit of the currency — centimes for CHF, and the equivalent for each asset) and is presented on the API as a value together with its currency and the number of decimal places, so no rounding is ever assumed by the reader. See Monetary Amount Format.

Time — when it was booked, when it takes effect

Explanation and governance — event, description, status, metadata

Record-keeping fields (every entry carries these)

Like every record in the platform, an entry also carries an identifier, created / modified timestamps and actors (who booked or last touched it, for the audit trail), and an active flag. These are set by the system, not by the person booking the entry, and exist so every posting is fully attributable.

A note on immutability. An entry's money and placement fields are written once, at posting, and never changed. Anything that looks like an "edit" — a correction, a reversal, a value-date change — is a new entry (or a new balancing journal), so the original line and the correction both stand in the history. This is what lets the ledger be trusted as the book of record.

API Reference

Ledger Management (V2)

GET /v1/ledgers

Returns a paginated list of ledgers. By default it lists Control Ledgers only (the Chart of Accounts view); subledgers are included only when explicitly requested.

GET /v1/ledgers/chart

Returns a balance-history time series for charting, not the Chart of Accounts tree. Each series is a list of {x, y} points (x = date, y = balance in major currency units) at the requested interval, taken from the daily balance snapshots. A ledger that aggregates other currencies, or is kept in a foreign currency, is plotted on its base-currency balance — the figure its monitoring ladder is compared with; a base-currency leaf on its posted balance. The ledgers to plot are selected with the required search.ledger_code.in query parameter (a comma-separated list of ledger codes); an optional color seeds the series colour. Requesting no valid codes is a validation error.

A series for a ledger that is under balance monitoring also carries its thresholds: the monitoring ladder in the same scale as the points (absolute major units, lowest limit first), each with its order and action, so a chart can draw the limit lines without knowing the configuration. The element is for drawing only — it does not carry the rule's comparison, which the monitor evaluates on the signed balance. Unmonitored ledgers carry no thresholds element.

The snapshot window is a half-open date range (search.snapshot_date.gte … search.snapshot_date.lt; .gt and .lte are accepted too); to include today's snapshot, end the range on tomorrow's date. The older start_date / end_date pair is still accepted and yields to the search.snapshot_date.* bounds when both are given.

Snapshots are not captured automatically yet: the series contains only the days generated on request with POST /v1/ledgers/history/generate (see Balance monitoring). Scheduled daily capture is an outstanding deliverable.

GET /v1/ledgers/{id}

Retrieve full details of any ledger (Control or Subledger) including current and available balances.

POST /v1/ledgers

Create a new Control Ledger. Note: Subledgers are managed automatically by the Account service.

PATCH /v1/ledgers/{id}

Change individual settings of a ledger — description, overdraft, dashboard visibility, direct booking, revaluation flag, and the control-ledger routing fields. Only the fields present in the request change; everything omitted keeps its value, so a single toggle (for example putting a ledger on the dashboard) is a one-field request. A status value is accepted for compatibility but not applied — a ledger has no status of its own; use the active flag.

Balance Holds (V2)

POST /v2/ledgers/holds

Place a new hold on a ledger. Decreases balance_available immediately.

GET /v2/accounts/{id}/holds

Retrieve all active holds for an account's subledger.

GET /v2/ledgers/holds/{id}

Get detailed information about a specific hold (reason, expiry, notes).

POST /v2/ledgers/holds/{id}/release

Release an active hold. Restores balance_available.

Technical Details

Automatic Subledger Creation

When a new Customer Account is created, the system executes an atomic transaction:

1. Creates the Account record.
2. Identifies the correct Control Ledger (Parent) based on currency and account type.
3. Creates a Subledger linked to that parent.
4. Updates the Account to reference this new Subledger.

Routing by customer type

Which control ledger a new account routes to is set directly on the control ledger's own properties — a Customer Types list (Corebanq Configurator → Ledger Browser → open the control ledger → "Customer Types"). Routing is resolved by purpose + customer type + currency: for each purpose (the everyday deposit account, and each segregation purpose such as pending settlement, compliance hold, or accruals for fees), a given customer type + currency routes to exactly one control ledger. The system rejects assigning the same purpose + type + currency to a second ledger, so routing can never become ambiguous — but the same customer type + currency can legitimately route to different control ledgers for different purposes (its deposits to one control, its fee accruals to another). Each control ledger manages the routing for its own purpose: editing "Customer Types" on the deposits control sets deposit routing, and editing it on the accruals-for- fees control sets fee-accrual routing, without the two colliding. This replaced an external configuration file — there is nothing to edit outside the ledger's own properties anymore.

Only a leaf control ledger — one with no child ledgers underneath it — can carry customer types. A parent or group ledger (e.g. the top-level "22" Customer Deposits group, or the "221" Type A Customer Deposits group) exists purely to aggregate its children's balances and can never itself receive an account booking, so it cannot carry a routing either; the Configurator hides the "Customer Types" control for such ledgers, and the API rejects the assignment if attempted directly. Set customer types on the specific currency leaf under the group instead (e.g. "2211" for a Type A customer's CHF deposits, not "221").

On a brand-new environment, the standard chart of accounts already ships with this routing — the public and exempt customer-deposit control ledgers come pre-assigned to their customer types when the chart is imported, so a fresh deploy can open accounts immediately without any manual setup. Chart import is tracked per file in seed_history (hash-aware): a partial import retries on the next boot, an edited chart file re-imports, and re-running a file only creates codes that are missing — existing ledgers are never rewritten or deleted. Because of that create-only rule, boot reconcilers re-align upgraded environments where the YAML gained fields after the row was first imported: purpose-control routing is backfilled, and direct_booking is enabled (one-way, false → true) on plain operational leaves whose seed declares direct_booking: true — never on control ledgers, whose flag is runtime state owned by the subledger machinery. Transit ledgers are not part of the chart: every code named in the ledgers.transit_ledgers.{CCY} config is provisioned at boot if missing, with the currency taken from the config key.

Subledger description pattern

Subledgers are named automatically. By default, every control ledger produces descriptions like "Customer Deposits Liabilities - Type A Customer (EUR) - Customer ABC Ltd" — the control ledger's own description plus the customer's name — with nothing to configure. Admins only need to touch this when one specific ledger should read differently: open that control ledger's own properties (Corebanq Configurator → Ledger Browser → "Subledger Description Pattern") and set an override template, e.g. {parent_description} (Direct Client: {customer_name}). Clearing the field returns that ledger to the automatic default — there is no need to define the same pattern on every ledger just to get sensible naming.

Supported tokens: {parent_description} (the control ledger's own description), {customer_name}, {account_id_short}, {iban_suffix}. If an override references a token with no value for the account being opened, the legacy "Account {id}" naming is used instead — a partially rendered description is never posted to the books.

Why one customer has several subledgers

The Current subledger created above is only one of several a customer may end up with. Every franc, euro or dollar the bank holds for a customer lives in a subledger: an individual ledger account that belongs to exactly one customer (or one of their accounts) and rolls up into a bank-level control ledger. Regulation requires that client money be clearly identified in the bank's own accounting, per client — not merely as a pooled wallet total:

• PSD2 Article 10 (safeguarding): client funds must be identifiable in accounting records and never commingled with any other person's funds.
• FCA CASS 7.16.22E (individual client balance method): the firm keeps one balance per client, and may keep one per product or business line per client.
• FCA CASS 15 / PS25/12 (in force 7 May 2026): records must distinguish relevant funds held for each client, support a daily internal reconciliation, a daily external reconciliation against the safeguarding bank, and a D+1 segregation check; a per-customer balance list (resolution pack) must be producible within 48 hours and records retained for 5 years.

A single account balance cannot separate "money the customer can spend" from "fees the customer owes the bank" or "funds reserved under a hold". Each of those is therefore its own subledger, each rolling into its own control ledger, so both the customer view and the bank's financial statements stay precise — and the safeguarding requirement can be computed directly from the ledger.

The structure: one customer, several accounts, several purposes

A customer may hold several accounts in the same currency (for example a main account and a payroll account, both CHF). Every account has its own Current subledger — the one created automatically above. Purposes that concern the relationship rather than a single account — such as fees receivable — are kept once per customer and currency:

The Fees receivable subledger is an asset (what the customer owes the bank), so it must roll into an asset receivables control ledger — never into fee income control 311, which would combine a receivable balance with earned revenue. The current chart does not yet seed such a receivables control, so the roll-up above is shown dashed and no live flow books the fees-receivable purpose until one is added and mapped (see Rollout note).

Reading the picture:

• Account-level purposes (Current, Hold) attach to one account. Two same-currency accounts never share a Current subledger; each account's spendable and held money stays separately traceable.
• Customer-level purposes (Fees receivable, collateral) attach to the customer. What Acme AG owes the bank in fees is one figure regardless of which account eventually pays it.
• Control ledgers hold only summary balances. They are populated exclusively by the roll-up of their subledgers; manual journals against a control ledger are rejected. This mirrors long-standing core-banking practice and structurally prevents the most common cause of subledger-versus-general-ledger reconciliation breaks.
• The sum of all subledgers under a control ledger always equals the control ledger's balance. This invariant is what the daily internal reconciliation verifies.

Codes in these examples. Account codes shown here (e.g. 2211 Type A CHF customer deposits, 311 Type A fee income) come from the standard Audax chart of accounts, grouped by leading digit: Group 1 Assets, Group 2 Liabilities, Group 3 Profit & Loss. The Fees receivable purpose is defined in the system, but the current chart does not yet seed a dedicated fees-receivable control ledger for its subledgers to roll into; until one is added, no live flow books to it (see Rollout note).

When each subledger is opened

Subledgers are opened lazily: only when the first booking of that purpose actually happens. Most customers never need a collateral subledger; none is created for them.

The customer-facing account is unchanged by any of this: the IBAN, statements and the primary spendable balance continue to work exactly as before. Purpose subledgers are the bank's internal precision, surfaced to operations and reporting.

Booking walkthrough 1 — a monthly fee

Fees are booked in two steps, and the split matters for safeguarding: the moment a fee is charged, that money stops being client money (the requirement drops), even though the cash may briefly remain inside the safeguarding boundary until swept.

Step 1 — Accrual (fee falls due; customer has not yet paid):

Step 2 — Settlement (collection from whichever account holds funds):

Because the receivable is a real ledger line per customer, the fee queue, dunning and write-off decisions read directly from ledger balances — and the safeguarding calculation can exclude charged-but-unswept fees from the client-money requirement while the external reconciliation still sees the cash, exactly the classification the regulator expects.

If the customer holds several same-currency accounts, settlement may debit any funded account's Current subledger (primary first). The receivable side is unaffected: it is customer-level.

Booking walkthrough 2 — incoming funds and suspense

Safeguarding duties start when funds are received, not when they are allocated. An incoming payment that cannot be applied immediately (unknown reference, name mismatch) is booked to an inward suspense account (281 Suspense – IWT – SIC in the standard chart) — a bank-level internal account, not a customer subledger — so the money is on the books from minute one:

Regulatory anchors for this flow:

• D+1 segregation check (CASS 15 / PSD2 Art. 10): funds received must reach a designated safeguarding account by close of the following business day. Because receipt is booked immediately, the daily D+1 check is a simple aging query over suspense and transit balances, with an audit trail of remediation postings.
• Suspense discipline: suspense accounts are open-item managed — every entry carries a reference and must be reversed by a matching entry, netting to zero per item. Aged-item reports over suspense are a standing operations control; long-outstanding items are the classic early-warning signal auditors look for.
• Individual client balances: the moment allocation happens, the money sits on the specific customer's Current subledger. The per-customer balance list required for the resolution pack is a direct ledger read, reproducible for any past business day from end-of-day balance snapshots.

Daily controls this structure enables

Negative individual balances are never netted against other clients when computing the requirement; they are excluded and surfaced separately as a funding obligation.

Rollout note

Existing accounts already have their Current subledger; nothing changed for them when multi-purpose subledgers went live. Purpose subledgers open lazily, the first time each is actually needed — the first hold, the first payment in transit, the first compliance action — never in advance and never simply because a customer is activated. A customer who is active for years without ever triggering a hold or a compliance action never gets one.

The mechanism described above — several subledgers per account or customer, opened lazily, rolling into their own control ledgers, with a control ledger refusing direct postings the moment it owns any subledger — is live today. No live flow has been moved onto a non-Current purpose yet (no product books to Hold, Fees receivable, Interest accrual or Collateral in production), so day-to-day behaviour is unchanged until a specific flow is migrated onto one. Safeguarding pool classification, end-of-day snapshots and the daily reconciliation views described above arrive in a second phase.

Identification Priority

For all entry and transfer endpoints, you can identify ledgers using:

1. UUID (ledger_id): Most performant, immutable.
2. Code (ledger_code): Human-readable (e.g., 2211-abc12345).
3. Numeric ID (ledger_num_id): Legacy support.

The system resolves them in the order listed.