A balance without a history: when payments need a proper ledger

A seller’s dashboard showed EUR 100. Now it shows EUR 70. A developer explains that the balance was corrected after a refund. Finance asks which refund, who approved it and why it was EUR 30. If the answer lives only in chat, the number is no longer a reproducible result. It is somebody’s latest opinion about the money.

An internal money ledger becomes useful when a product tracks obligations and several kinds of fund movement. For every amount, it should reveal the reason for change, affected parties and supporting evidence. This article proposes an operating model. Statutory accounting, tax treatment and retention requirements need separate agreement with the responsible specialists.

Which balance are you promising to show?

Start with the question the interface promises to answer. What we owe the seller, what can be paid out now and what is held with the PSP describe different amounts. If they share one label, developers may keep correcting allegedly wrong numbers that actually answer different questions.

The proposed model tracks confirmed obligations, availability restrictions and actual movements separately. A hold can reduce the amount available for payout without extinguishing the obligation. A submitted payout request still needs a documented outcome. Support should be able to see the definition of each number and the records included in its calculation.

Double-entry recording provides a consistency check: the debit and credit sides of a transaction must balance. TigerBeetle’s accounting documentation explains this principle and how an account’s type determines the effect of debits and credits. This is a control mechanism, not automatic proof that the economic classification is correct.

Follow one illustrative EUR 100 payment

Suppose an agreed marketplace model allocates a confirmed payment as follows: EUR 97 is owed to the seller and EUR 3 is the platform’s fee. The PSP separately deducts EUR 2 as the platform’s processing expense. Taxes, reserves and other deductions are excluded from this teaching example.

After those events, the platform’s claim on the PSP is EUR 98. Its obligation to the seller is EUR 97. Its economic result before other expenses is EUR 1. The relationship is checkable: 98 = 97 + 1. If the seller dashboard displays EUR 98, the implementation may have confused the provider balance with the amount owed to the seller.

Now restrict EUR 20 of the seller’s EUR 97 under an agreed basis. The available payout is EUR 77, while the total obligation remains EUR 97. Releasing the restriction restores availability rather than creating another sale. A product with different contractual treatment must reflect that treatment explicitly instead of forcing its numbers into this example.

For each record, retain the operation reference, currency, reason, event time, recording time and link to the original payment. The two timestamps matter: a message received today may describe yesterday’s event. Agree how events enter reporting periods so that an overnight import does not silently alter a report already distributed.

A correction should leave a trail

In this model, an incorrect entry is corrected through a linked adjustment rather than erased. The chain shows the original event, discovered error and authorised correction. The adjustment identifies its author, reason and supporting evidence. Another employee can then reconstruct the case without access to a developer’s private chat.

An immutable journal can still preserve incorrect data perfectly. It cannot independently know that a payment belongs to a different seller. Checks on ownership, permitted transitions and independent reconciliation with the PSP and bank remain necessary. Balanced totals detect some errors, but two offsetting mistakes can leave the grand total unchanged.

Before a manual correction executes, show its expected effect. Which party’s amount changes? Which availability figure changes? How will the next report reflect it? Apply the agreed approval authority and second-person controls for consequential adjustments. A comment saying finance requested this is not a substitute for the actual approved instruction.

Currency and rounding belong in the model

Do not combine euros and dollars in one money account without an explicit exchange operation. Store currency and amount scale together. Stripe generally expects amounts in minor units, with special treatment for certain currencies and payouts. Its currency-format guidance illustrates why a universal multiply-by-one-hundred rule is unsafe.

Choose an exact numerical representation and rounding rules at each boundary in your own model. A teaching test that divides one euro among three participants must explain the remaining cent. Awarding it to whichever participant happens to be processed first produces an unstable financial result. A repeat of the same approved calculation should not change the allocation.

Start with one disputed balance

Choose a real operation type and use artificial data to design the model. Reproduce the balance from its records without reading the stored balance field. Then add a duplicate event, late report, partial correction and availability restriction. If different employees obtain the same explainable amount, the model is beginning to work.

Reconciliation asks whether your records agree with external evidence. The ledger asks why you believe that amount is owed in the first place. Without the second question, the first easily becomes a daily exercise in making the numbers look equal.