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.

See also:

• Reconciliation API
• Journal Transactions
• Ledger Chart

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 typically don't hold individual customer funds directly.
2. Subledgers: Special ledgers created automatically for every Customer Account. They are the actual containers for customer money.
3. Customer Account: The user-facing entity. In V2, the account balance is a projection of the associated Subledger's state.

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

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 either released or "settled" (converted into a real debit entry).

Hold Scenarios:

• Card Authorizations: A merchant authorizes $50. A hold of $50 is placed.
• Administrative Hold: Compliance department freezes $10,000 pending verification.
• Overdraft Protection: Negative holds can be used to temporarily increase buying power.

API Reference

Ledger Management (V2)

GET /v2/ledgers/control

Returns a paginated list of Control Ledgers only. Best for building Chart of Accounts tree views.

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.

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.

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., 2201-abc12345).
3. Numeric ID (ledger_num_id): Legacy support.

The system resolves them in the order listed.

Implementation Roadmap

For a detailed analysis of the current accounting architecture and recommendations for future improvements (including strict available vs current balance separation via DSL), please refer to Accounting Architecture Analysis.