Ledgers, reconciliation, and settlement risk
Make balances explainable and prevent money from appearing twice.
Balance the books. Explain the difference.
Enlarge to read every label and explore the connections
A balanced journal is necessary, but independent records must also agree. Reconciliation explains differences instead of hiding them.
Compare the two sides of the journal.
Reconcile the processor total to bank cash.
Keep the fee and transaction references explicit.
The bank says $9,970. The processor says $10,000. The app says everyone has been paid. No one is lying; the $30 fee is missing from one view. A ledger is the part of a fintech that must be less imaginative than its marketing.
Record balanced obligations
- EventIdentify the economic change
- PostUse defined debit and credit accounts
- CheckBalance and validate account meaning
Double-entry accounting records each event with equal total debits and credits. It helps expose incomplete entries, but a balanced journal can still be wrong. Two incorrect accounts can balance perfectly. Use account definitions, posting rules, and event references alongside the arithmetic.
For a simplified incoming $100 customer balance, debit cash and credit a customer liability. The firm holds an asset and owes the customer. This is not automatically revenue. Keep a chart of accounts that distinguishes customer funds, fees, receivables, reserves, and settlement clearing. Accounting treatment in a real product requires the relevant professional policy.
A simplified platform ledger might record an increase in cash at a settlement bank and an equal increase in the amount owed to merchants. The entry balances, but that fact alone does not prove that the bank actually received the money. A balanced ledger can faithfully record a wrong assumption. Independent settlement and bank records supply the external evidence needed to test the assumption.
The choice of accounts also communicates the business model. Customer obligations, merchant obligations, fees, reserves, and amounts awaiting investigation should have clear meanings. Do not use a suspense account as a permanent home for unexplained differences. Assign an owner, an age, a reason, and a resolution path to each unresolved item. The longer an item stays unexplained, the less useful a single aggregate cash total becomes.
Inside the mechanism. Double-entry accounting provides a conservation check within a posting: total debits equal total credits in the relevant unit. It does not prove that the business event was valid, unique, correctly classified, or posted to the correct customer. Keep a journal identifier, business action key, account references, amount, currency, and effective time. A balanced duplicate is still wrong. Reconciliation needs an independent expected population, not only a check that the ledger sums to zero.
A concrete example. The ledger records what the platform owes and the assets supporting those obligations. A balanced entry can still encode an incorrect external assumption. The batch begins with $215,000 of instructions and $206,400.00 of captured value. At the observation cutoff, $6,192.00 remains pending. After the stated refunds, fees, and restrictions, $166,977.60 is available for payout. The unresolved instruction count is 2; an unknown external result is handled separately from a known decline.
When the assumption fails. Expected settlement is booked as cash before independent confirmation. Use a receivable state and reconcile the bank and processor records. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
The ledger records what the platform owes and the assets supporting those obligations. A balanced entry can still encode an incorrect external assumption.
- Cash asset
- Money held by the firm
- Customer liability
- Money the firm owes a customer
Illustrative journal
Illustrative data; not a real customer record or a prescribed policy.
- Debit cash100 USD
Asset increase
- Credit customer liability100 USD
Obligation increase
- Revenue0 USD
Deposit is not a fee
Holding money differs from earning it
It can create an equal customer liability. Holding money differs from earning it.
- Failure mode 1avoid
- Every cash receipt is profit. Cash and income are different concepts.
- Failure mode 2avoid
- Balanced journals prohibit liabilities. They can record both assets and liabilities.
- Failure mode 3avoid
- The payment reference decides revenue. Accounting meaning requires a posting rule.
Make retries financially idempotent
- IdentifyStable logical operation key
- CommitPost once under a unique constraint
- RetryReturn the prior operation result
Idempotency means repeating a logical operation does not repeat its intended effect. Bind the key to a defined operation and payload. A retry of the same payment should reuse the key; a genuinely new payment needs a new one. Reject conflicting reuse rather than silently changing the amount.
Provider idempotency is one boundary, not the whole system. Use unique journal-event constraints and transactional posting in your own database. A webhook can arrive twice, or a worker can crash after posting but before acknowledgment. The database must make duplicate money creation impossible within the defined operation, even when delivery is at least once.
Idempotency requires agreement about the boundary of one intended action. Reusing the same key for the same refund should return the existing result. Reusing it for a different amount should produce a controlled conflict under the chosen contract. Database uniqueness, stored request fingerprints, and transactional writes can help enforce that boundary. The protection must survive concurrent requests and process restarts. An in-memory list of recently seen keys disappears at exactly the moment a recovering service may receive a wave of retries.
Inside the mechanism. Idempotency belongs to a defined operation and key scope. A repeated request with the same business intent should return or resolve the existing result rather than create another effect. Keep the request fingerprint and reject incompatible reuse. Provider retention and retry behavior differ, so local durability and external reconciliation remain necessary. In Stripe’s documented API behavior, the first executed result is retained for a key, including an error result; this is not a general guarantee for every payment API.
A concrete example. Two workers receive a refund request while earlier attempts are still in flight. Correct arithmetic in each worker does not prevent a shared-state race. 85 intended requests generate 89 processing attempts under this retry assumption. Capacity is 120 attempts per interval, and the critical path consumes 150 ms of a 220 ms budget. The request-based SLO view observes 100 bad requests against an illustrative allowance of 100. These measurements must be connected to the financial effect and control evidence before declaring recovery.
When the assumption fails. Both requests consume the same remaining refundable amount. Use one action key and an atomic state transition with defined conflict handling. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
Two workers receive a refund request while earlier attempts are still in flight. Correct arithmetic in each worker does not prevent a shared-state race.
- Duplicate delivery
- Same event arrives again
- New obligation
- Different business event needs a new entry
Retry specimen
Illustrative data; not a real customer record or a prescribed policy.
- Operationpay-71
Stable payment identity
- Attempt3
Transport count only
- Journal entries1 set
One financial effect
Transport retries must not create new value
A unique event constraint at the journal boundary. Transport retries must not create new value.
- Failure mode 1avoid
- A dashboard warning tomorrow. That detects damage after posting.
- Failure mode 2avoid
- A random new payment identifier. It hides the duplicate.
- Failure mode 3avoid
- Only a client-side button lock. Workers can retry without the client.
Reconcile independent records
- MatchConnect independent references
- ExplainClassify differences
- ResolvePost or correct with evidence
Reconciliation compares records that describe the same obligations from different systems. Match transaction-level references first, then check aggregate totals. Equal totals can hide two offsetting errors. A missing $100 credit and an extra $100 credit can cancel in a summary.
Classify breaks as timing, fee, currency, duplicate, missing, or unexplained. Assign an owner and aging limit. Do not force-match a break merely to make a report green. Store the matching rule and supporting records so the resolution can be reproduced. Automated matching is valuable when its exceptions remain visible.
Inside the mechanism. Use a three-way comparison when the system has an internal instruction, a processor observation, and a ledger effect. Classify missing-internal, missing-external, amount-mismatch, duplicate, and timing exceptions separately. Net totals can hide offsetting errors. Compare stable identifiers and gross components before accepting an aggregate match. A timing exception needs an age, expected next evidence, and an owner; otherwise the temporary difference becomes a permanent hiding place for loss.
A concrete example. The platform compares its payment records, processor settlement records, and bank cash. Matching totals alone can hide offsetting errors. The batch begins with $367,500 of instructions and $352,800.00 of captured value. At the observation cutoff, $10,584.00 remains pending. After the stated refunds, fees, and restrictions, $286,826.40 is available for payout. The unresolved instruction count is 2; an unknown external result is handled separately from a known decline.
When the assumption fails. A missing payment and a duplicate payment happen to have equal amounts. Reconcile stable identifiers, amounts, currency, and cutoff as well as totals. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
The platform compares its payment records, processor settlement records, and bank cash. Matching totals alone can hide offsetting errors.
- Total equality
- Aggregate amounts agree
- Item agreement
- Individual obligations also match
Settlement comparison
Illustrative data; not a real customer record or a prescribed policy.
- Processor gross10000 USD
Sales before fee
- Fee30 USD
Explicit deduction
- Bank receipt9970 USD
Gross less fee
The difference reconciles to an identified item
The documented $30 fee. The difference reconciles to an identified item.
- Failure mode 1avoid
- Automatic fraud. The facts support a fee explanation.
- Failure mode 2avoid
- A $30 customer refund. No refund evidence was supplied.
- Failure mode 3avoid
- An exchange gain. No currency conversion was stated.
Distinguish liquidity from solvency
- ForecastTime-specific available funds
- StressDelay uncertain inflows
- RespondUse approved funding sources
A solvent firm can still lack cash at the moment a payout is due. Assets may be illiquid or arrive after the obligation. A liquidity view therefore needs timing, eligible funding sources, currencies, and stress assumptions. A single end-of-day balance can hide an intraday shortfall.
Build a cash ladder: opening usable funds, expected inflows, committed outflows, and buffer. Separate certain inflows from optimistic forecasts. If a settlement partner delays funding, determine which obligations can still be met and which require an approved contingency. Customer funds and restricted reserves are not a general-purpose emergency wallet.
Inside the mechanism. Solvency asks whether resources can cover obligations under the relevant valuation and loss assumptions. Liquidity asks whether usable funds are available when an obligation falls due. A recoverable receivable next month may not pay today’s settlement. A restricted reserve may not be usable for operating expenses. Build a dated cash view by currency and legal entity, then keep it separate from an expected-loss model and the accounting balance sheet.
A concrete example. The platform has assets sufficient on paper while a funding delay prevents it from meeting today’s obligations. The distinction is one of usable timing and location. The case has $850,000 of exposure. Its stated one-year PD and LGD imply $11,687.50 of expected loss, while the cover analysis leaves $365,000.00 of stress exposure. Monthly cash coverage is 0.85×. These are separate measures: one describes an average under probability assumptions, one describes available cover, and one describes a period’s funding capacity.
When the assumption fails. A concentrated settlement partner misses a cutoff. Build a currency-and-time cash ladder and stress the accessible funding sources. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
The platform has assets sufficient on paper while a funding delay prevents it from meeting today’s obligations. The distinction is one of usable timing and location.
- Solvency
- Assets relative to obligations
- Liquidity
- Usable funds at the required time
Illustrative cash ladder
Illustrative data; not a real customer record or a prescribed policy.
- Available now80000 USD
Eligible cash
- Due now100000 USD
Committed payouts
- Arrives tomorrow50000 USD
Cannot fund today automatically
Today requires $100,000 against $80,000 available
$20,000. Today requires $100,000 against $80,000 available.
- Failure mode 1avoid
- Zero because tomorrow brings cash. Tomorrow does not meet today without funding.
- Failure mode 2avoid
- $50,000. That is the later inflow.
- Failure mode 3avoid
- $180,000. Adding cash and obligations does not measure a gap.
Reverse with a trace
- DetectIdentify the incorrect posting
- ReverseLink an authorized correction
- VerifyReconcile the corrected balances
Correct mistakes with linked entries and a reason. Deleting a journal record removes the explanation of what the system believed and when. A reversal should reference the original entry and preserve approval evidence. Recompute downstream balances from the corrected history.
Use permissions that separate preparation from approval for high-impact adjustments. Monitor manual adjustments by count, value, account, and operator. A pattern of tiny adjustments may indicate a rounding defect; a few large adjustments may indicate a mapping error or misuse. The goal is an explainable trail, not a journal that appears never to have made a mistake.
Inside the mechanism. A reversal should preserve the original posting and create linked compensating entries. Deleting or editing the original record destroys the explanation for downstream statements, reconciliation, and customer communications. A partial reversal needs its own amount and remaining reversible balance. Protect that balance from concurrent requests. The operational result should identify both the corrected financial position and any external effect that still needs a separate refund, return, or recovery process.
A concrete example. A correction must undo the intended economic effect while preserving the original journal. Deleting the old row would remove the evidence needed to explain the account. The batch begins with $63,200 of instructions and $60,672.00 of captured value. At the observation cutoff, $1,820.16 remains pending. After the stated refunds, fees, and restrictions, $49,022.98 is available for payout. The unresolved instruction count is 2; an unknown external result is handled separately from a known decline.
When the assumption fails. A support adjustment overwrites an earlier payment entry. Post linked compensating entries with a reason and reconcile the corrected balance. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
A correction must undo the intended economic effect while preserving the original journal. Deleting the old row would remove the evidence needed to explain the account.
- Deletion
- Erases the historical explanation
- Linked reversal
- Preserves the event and its correction
Correction specimen
Illustrative data; not a real customer record or a prescribed policy.
- Originaljournal-18
Wrong clearing account
- Reversaljournal-24
Offsets journal-18
- Replacementjournal-25
Uses approved account mapping
The history remains explainable
A linked reversal and correct replacement. The history remains explainable.
- Failure mode 1avoid
- Delete it without a record. That destroys the audit trail.
- Failure mode 2avoid
- Change all customer balances manually. That bypasses event meaning.
- Failure mode 3avoid
- Hide it from reconciliation. The obligation still needs resolution.
Chapter connections
This chapter builds on Instant payments and cross-border transfers. Use the glossary for terminology and risk mathematics for formulas and worked calculations.