Put your chart of accounts design into practice
Clone the Formance Ledger on GitHub, run it locally, and post the PSP settlement transaction from the example above against a chart of accounts you designed yourself.
Your bank shows one omnibus account balance, but your ledger has to prove which of a million customers owns every cent of it, on demand. The account structure you pick before your first posting decides whether that proof is a query or a forensic reconstruction.
For infrastructure-led payment products, engineering and finance should jointly own the chart-of-accounts design. The structure you choose determines how you can reconcile ledger records and what a regulator can verify. It also determines what breaks when transaction volume grows.
Fintech scale means the operating conditions that break small-business patterns. This includes customer counts reaching into the millions, multiple payment rails settling on different clocks, several PSP (payment service provider) accounts that hide per-customer ownership, and reconciliation cadences measured in hours rather than months.
Every new payment rail triggers a debate about where its settlement account lives, every product launch adds accounts that don't cohere with the last batch, and the reconciliation requirements carry a list of special cases.
This article walks through designing a chart of accounts end to end, including definitions, failure modes, namespace structure, omnibus modeling, four pre-launch decisions, posting-layer enforcement, and a checklist.
A traditional chart of accounts is a numbered list of controller-facing accounts (1000s for assets, 2000s for liabilities, 3000s for equity, 4000s for revenue, and 5000s for expenses) designed for periodic financial reporting.
A fintech chart of accounts is a path-addressed namespace designed for real-time customer attribution, machine-queryable by segment, and updated on every transaction.
Four differences matter for a fintech chart of accounts design:
Traditional charts summarize the entity's financial position for reporting, while fintech charts prove per-customer ownership of omnibus funds on demand.
Traditional charts use numeric codes that answer one question (account type). Fintech charts use ordered path segments that answer many (owner, context, rail, and state).
Fintech charts contain millions, because each customer, each PSP boundary, and each settlement state is its own account. Traditional charts only contain hundreds of accounts.
Traditional charts update monthly or quarterly, while fintechs must update charts per posting, and every posting must satisfy an attribution invariant at write time.
A chart of accounts fails at fintech scale when omnibus attribution breaks, account counts outgrow the structure, and daily reconciliation becomes impractical under FDIC and FCA rules.
Your bank sees one balance, and your ledger chart of accounts must prove who owns every cent.
Without per-customer attribution encoded in the account structure, safeguarding reconciliation degrades from a balance comparison into a forensic reconstruction across all accounts and transactions.
A structure sized for hundreds of accounts won't scale to millions of customers. Numeric-range charts assume account creation is a controller task, but at fintechs, accounts scale programmatically on every signup and every new PSP boundary.
Regulatory proposals from the Federal Deposit Insurance Corporation (FDIC) and safeguarding rules from the Financial Conduct Authority (FCA) increasingly require firms to reconcile internal records against bank records daily.
When a chart of accounts cannot preserve attribution across omnibus accounts, drift between the ledger and partner-bank records can reach eight- or nine-figure discrepancies before detection.
This leaves customer funds unaccounted for and recovery dependent on bankruptcy-style reconstruction.
A hierarchical namespace requires path segments that work as operational query keys, namespace rules that preserve double-entry correctness, and an owner segment without which attribution breaks.
Paths like users:8451:available and counterparties:psps:provider:settlement:pending answer multiple operational questions.
Sum over users:*:available and you have total customer liability. Sum over counterparties:psps:*:settlement:pending and you have in-flight funds by rail.
Moving from numeric ranges to a path-addressed namespace changes which queries the ledger can answer. But the double-entry accounting invariant must hold.
Segment order matters because every segment must be individually queryable, and metadata should never be added into a segment.
The owner segment is the first path element that ties every balance back to a specific customer, PSP, or platform account.
A flat namespace hides ownership. A single account label pooling billions of dollars of customer funds cannot answer who owns any of it, because no owner segment exists to query.
Formance Ledger is an open-source, programmable core ledger that unifies fiat and digital assets with regulatory-grade traceability, and its account model is a path-addressed namespace shaped exactly like this.
A named, reconcilable boundary account appears once in your chart of accounts and is offset by per-customer liability accounts whose total must match the funds introduced through the boundary.
The bank or PSP sees a single pooled balance, while the ledger holds the per-customer attribution the pooled account cannot.
The pattern combines a boundary such as counterparties:psps:provider:settlement, whose running balance tracks the cash introduced through the PSP, with a customer namespace (users:{id}:available) that tracks who owns the pool.
For a bank-held omnibus account, an owner-first path such as platform:banks:provider:omnibus serves the same reconciliation role. The invariant requires the boundary balance to equal the sum of customer balances after every transaction.
Boundary movement and customer attribution must occur in one atomic transaction, and never in separate writes that can diverge.
A payment service provider (PSP) settlement batch of $2,500,000.00 can be posted atomically by sending the batch from the named PSP boundary and attributing the full amount across customer paths in the same transaction. The boundary's running balance is the reconcilable mirror, so you don't need a second full-value posting.
The example below is written in Numscript, Formance Ledger's transaction DSL for expressing atomic multi-account postings.
The three customer allocations total $2,500,000.00. The named PSP boundary funds the allocations directly and records the cumulative amount introduced from outside.
All three send statements are committed as a single transaction, so either all allocations post or none do.
// PSP_SETTLEMENT
// Event: attribute a $2,500,000.00 PSP settlement across three customers
send [USD/2 125000000] (
source = @counterparties:psps:provider:settlement allowing unbounded overdraft
destination = @users:8451:available
)
send [USD/2 87500000] (
source = @counterparties:psps:provider:settlement allowing unbounded overdraft
destination = @users:2210:available
)
send [USD/2 37500000] (
source = @counterparties:psps:provider:settlement allowing unbounded overdraft
destination = @users:9034:available
)
set_tx_meta("event_type", "psp_settlement")
set_tx_meta("settlement_id", "stl001")
The script debits the PSP boundary and credits three customer accounts in one transaction, so the boundary balance always equals the sum of customer balances. If any allocation fails, the whole transaction fails, and no partial attribution reaches the ledger.
Four design decisions determine whether a chart of accounts fintech scales: per-customer accounts, suspense placement, fiat and digital-asset unification, and append-only evolution. Each decision has a recommended answer, and each is expensive to reverse after launch.
Each customer should get their own ledger account when the core ledger addresses accounts by path segment.
With a ledger designed for path-based aggregation, accounts under users:* become queryable records rather than controller-facing report lines.
Per-customer accounts make safeguarding reconciliation a balance comparison the ledger can find. Metadata-only attribution makes reconciliation a join across application tables whose correctness must be proven separately.
Per-customer accounts also eliminate write contention on a single aggregate liability row under high concurrency. If the ledger cannot query by segment, keep aggregate control accounts in the chart of accounts and push per-customer detail into a queryable sub-ledger namespace.
Suspense accounts belong under the platform namespace, typed so balances touch neither profit and loss (P&L) nor customer liabilities. When posting idempotency fails and a duplicate posting lands, remediation is a reversing posting that mirrors the original posting.
Ledger immutability makes the correction auditable. Use the typed suspense account only to hold an unresolved discrepancy, and then post the final correction to the proper account.
Place suspense at platform:suspense:duplicates or similar, and treat any non-zero balance as an open work item with an owner and a deadline.
Fiat and digital assets share one namespace, with the owner encoded first, the asset held on the balance, and the settlement state encoded in the path.
The currency or asset code appears on the posting amount (for example, USD/2), and not in the account path, so a single account can hold multiple assets.
A digital asset custody balance and a bank omnibus balance are both modeled as assets. Yet, they differ in rail and settlement timing. Different settlement timing across fiat and blockchain rails requires pending and settled states in the account path, where a query can see them.
Settlement states should not live in application code, where reconciliation cannot see them. Posting funds from users:8451:pending to users:8451:available records settlement timing in ledger history. The fiat-to-digital-asset playbook covers the two-container problem end to end.
A fintech chart of accounts should evolve append-only. Add paths, and never rename or delete the posting. Renaming accounts complicates historical queries and period-over-period reporting, while a new path alongside the preserved old one avoids the disruption.
Migrating a homegrown single-column balance table requires paired liability and asset accounts and an opening posting per customer.
Verify that the sum of opening entries equals the sum of balances, and route any residue to the suspense path defined above.
Chart of accounts rules only hold when the ledger rejects invalid paths, unbalanced postings, and unauthorized overdrafts at write time.
A rule enforced by code review is a suggestion, and manual review fails at exactly the moments large-value errors occur. Input errors of many orders have cleared multi-person review at major banks and are caught only by after-the-fact detective controls.
Formance Ledger implements the write-time enforcement described here. It programmatically enforces double-entry accounting, commits multi-account postings atomically, and exposes a multi-segment account namespace and Numscript for expressing transaction intent. Path-authorization and overdraft policies belong in validated transaction logic and integration controls.
Write-time enforcement also changes what reconciliation costs, and write-time guarantees reduce the internal side of daily reconciliation to a per-rail balance comparison.
External timing differences, missing provider records, and fee postings still require exception handling.
Close six items before the first production posting: namespace segmentation, omnibus attribution, suspense placement, asset and state encoding, append-only evolution, and write-time validation.
A chart of accounts that closes all six items ensures that as the fintech scales, safeguarding reconciliation stays a balance comparison. It also ensures new PSPs can be added without renaming existing paths, and regulators can trace any pooled balance back to its underlying customers on demand.