In simple systems, a balance seems to be just a number: R$ 12,450 available. In financial infrastructure, however, that number alone is almost useless if the platform cannot explain how it arrived there.
Was it a capture? A fee? A refund? A chargeback? A transfer? An early payout of receivables? An operational adjustment? Which event happened first? Which movement corrected the previous one? Which amount belongs to which merchant?
This is where the ledger comes in.
A ledger is the structure that records financial movements traceably so balances can be derived from facts, rather than treated as mutable values with no history.
What is a ledger?
A ledger is a structured record of entries representing movements of value between accounts or financial positions.
Instead of storing only “current balance = 100,” the system maintains the sequence of facts that produced that balance.
This makes it possible to reconstruct the past, audit changes, and understand why a particular amount is available, reserved, pending, or already settled.
Is a ledger the same as a transaction database?
Not necessarily.
A payments table may record authorization, capture, and charge status. That is the transactional domain.
The ledger records financial impact.
A capture can generate one or more entries. A refund generates new entries. A fee is another movement. A payout moves funds between different positions.
Mixing everything into the same payment row usually makes the finances harder to explain.
Is a balance a fact or a result?
Ideally, a balance is a result.
It can be calculated by summing the entries for an account at a given time.
For performance, many platforms maintain snapshots or materialized balances. But these values should remain reconcilable with the movement trail.
If a balance can change without an entry explaining the change, auditability becomes weak.
What is double-entry bookkeeping?
It is the principle that each movement has at least two sides and that debits and credits must balance within the modeled accounting system.
If R$ 100 leaves one position, that R$ 100 enters a corresponding position.
The goal is not merely to follow accounting terminology. It is to make inconsistencies detectable.
If an entry changes an account without a counterpart, the system can detect that the equation does not balance.
Do I need to use debits and credits?
You do not have to use traditional accounting language exactly in the application interface, but the principle of balanced entries is extremely useful.
Many financial bugs arise when code simply increments and decrements numbers in different places without a single conceptual transaction.
A ledger forces the question: where did the value come from, and where did it go?
What is an account in the ledger?
An account is a logical position that accumulates entries of a particular nature.
It can represent merchant funds, amounts awaiting settlement, fees, reserves, chargebacks, internal cash, or another category required by the domain.
A ledger account does not need to correspond directly to a bank account.
It is an abstraction for organizing value within the system.
Is a ledger the same as the official accounting general ledger?
Not necessarily.
An operational payment ledger can be created to track the platform's financial events and provide a basis for reconciliation.
Official accounting may follow a chart of accounts, tax rules, and policies that go beyond the transactional domain.
The two can integrate, but should not automatically be treated as the same thing.
What is the relationship between a payment and a ledger entry?
A payment represents the intent and lifecycle of a charge.
A ledger entry represents a financial impact associated with an event.
An authorization, for example, may not generate the same type of entry as a capture, depending on the business model.
A capture may create a receivable. A refund reduces a position. A fee creates a separate movement.
The relationship can be one-to-many.
Why not store everything as columns in the payment?
Because the history grows.
Initially, the table has amount and status. Then captured_amount, refunded_amount, fee_amount, chargeback_amount, net_amount, reserve_amount, and dozens of flags appear.
Each new event needs to modify the same row.
This makes it difficult to reconstruct the exact sequence and increases the risk of overwriting information.
A ledger records events as additional entries.
Should a ledger be immutable?
The safest rule is to avoid editing financial entries after they have been posted.
When there is an error, a correction or reversal entry is created.
This preserves the audit trail.
Immutability does not mean there will never be a correction. It means the correction also becomes a visible fact.
How do you correct an incorrect entry?
Create a movement that offsets the incorrect entry and another that records the correct amount, according to the system design.
Do not silently erase the past.
This makes it possible to understand that an error occurred and how it was corrected.
In a financial investigation, that history can be essential.
What is a reversal?
A reversal is an entry that offsets the effect of another movement.
It can be used to correct an internal error or represent a financial operation that undoes an earlier position.
It is important to distinguish an accounting reversal from a refund, cancellation, or chargeback in the payments domain.
The concepts may produce similar entries but have different causes.
Does authorization belong in the ledger?
It depends on what the ledger is intended to represent.
If authorization creates only a commitment and not a financial movement recognized by the platform, it may be better represented in another domain.
If the product needs to track reserved amounts, the ledger can have reserve accounts or entries separate from available funds.
The important thing is not to mix “reserved” with “settled.”
What is an available balance?
It is the portion that can be used or withdrawn under the product's rules.
It may differ from the total balance.
A platform may have captured amounts not yet released, risk reserves, pending chargebacks, or movements being processed.
That is why displaying a single number without semantics is dangerous.
What is a pending balance?
It is a value position that exists economically within the domain but is not yet available for a particular action.
A recent capture may be awaiting settlement. A sale may be subject to a waiting period. A payout may be in transit.
The ledger allows these positions to be separated without losing the links between them.
What is a reserved balance?
It is value temporarily segregated to cover risk, an obligation, or a future operation.
A reserve should not be implemented simply as “available_balance -= x” without recording where the money went within the model.
If the system moves value from available to reserved, that movement needs to be explainable.
How do fees enter the ledger?
As their own movements.
A R$ 100 sale can create a gross position of R$ 100 and a R$ 3 fee, leaving R$ 97 net for the merchant.
Storing only R$ 97 loses information about gross revenue and cost.
Separating the components improves reconciliation and reporting.
How do refunds enter the ledger?
A refund creates a new financial effect linked to the original charge.
If the sale generated a credit for the merchant, the refund must reduce the position according to the product model.
With a partial refund, only part of the amount is moved.
This allows the balance to reflect the history without erasing the original sale.
What about chargebacks?
A chargeback is also a later event.
It can remove value, create a reserve, or generate additional adjustments.
Because a dispute can occur weeks later, the ledger needs to accept late movements related to older events.
This is one reason not to “close” the financial history on the day of the sale.
What about payouts?
A payout is a transfer of value from the merchant's internal position to an external account or another destination.
In the ledger, it normally reduces an available account and moves the value to an in-transit or completed payout position, depending on the design.
When the bank confirms the movement, the platform updates the payout lifecycle without needing to erase the original entry.
Can a ledger have different currencies?
Yes, but each entry must explicitly preserve the currency.
Adding R$ 100 and US$ 100 as “200” is semantically invalid.
Accounts can be segregated by currency, and conversions must generate specific movements with an exchange rate and reference.
How do you model foreign exchange?
Foreign exchange should be treated as an event that transforms a position in one currency into another position in a different currency, with an exchange rate and possible fees.
The system needs to store the source amount, destination amount, and conversion context.
This makes reconciliation and customer explanations easier.
What is a journal entry?
It is a logical grouping of entries belonging to the same financial event.
For example, a capture may generate several balanced lines, but they all share an internal journal or transaction ID.
This grouping facilitates atomicity and investigation.
Why does atomicity matter?
Because half a financial movement is inconsistent.
If a debit is recorded and the corresponding credit fails, the ledger no longer balances.
The entries in a journal need to be persisted as an atomic unit.
How do you ensure that the ledger balances?
Each journal should satisfy the balancing equation defined by the model.
In addition, verification routines can recalculate sums and look for broken entries.
Database invariants and domain validations are better than relying only on application tests.
Can the ledger be reconstructed from events?
It can, if the events contain sufficient information and are immutable.
Some architectures use event sourcing. Others maintain the ledger as its own database generated from domain events.
The main point is that the ledger needs a reliable, reproducible source.
Are event sourcing and a ledger the same thing?
No.
Event sourcing is a pattern in which state is derived from a sequence of events.
A ledger is a financial-recording domain.
They work well together, but a system can have a ledger without adopting event sourcing across the entire application.
Can I use a regular relational database?
Yes.
A ledger does not require exotic technology.
PostgreSQL, for example, can support robust entries when the schema, constraints, transactions, and indexes are well designed.
The main challenge is modeling, not the database brand.
What is idempotency in the ledger?
It means ensuring that the same external event does not generate duplicate entries.
If a capture webhook arrives twice, the corresponding journal should be created only once.
This typically requires a unique key tied to the source event or financial intent.
How do you handle out-of-order events?
The ledger needs to apply only movements valid for the domain and preserve references.
A refund should not exist without an eligible charge, for example.
If the event arrives before the expected state because of an integration delay, the application can queue it, reconcile it, or query the source.
Simply sorting by arrival time is unsafe.
Is a creation timestamp enough?
No.
It is useful to distinguish when the economic event happened, when it was received, and when it was posted internally.
These times can differ.
This distinction helps with reconciliation and delay investigations.
How does the ledger help reconciliation?
It provides an internal trail against which external movements can be compared.
If a PSP reports R$ 10,000 net, the platform can add up expected captures, fees, refunds, and adjustments.
When it does not balance, the discrepancy can be traced to a movement.
Without a ledger, the comparison tends to rely on snapshots.
How does the ledger help support?
A dashboard can show the sequence of movements for a charge or account.
The support representative no longer has to say “that is the balance because the system calculated it” and can explain which events increased or reduced the position.
This reduces reliance on engineering for simple financial questions.
How does the ledger help auditing?
Auditing requires evidence.
Who generated the movement? Which external event originated it? Which journal contains it? Was there a correction? What was the sequence?
An immutable, well-referenced ledger answers these questions.
How do you control concurrency?
Two operations may try to spend the same balance simultaneously.
The platform needs to use transactions, locks, versioning, or another technique that preserves invariants.
Calculating a balance and then updating it without protection can allow an improper negative balance.
Is a negative balance always an error?
Not necessarily.
Some products allow negative balances because of chargebacks, credit, limits, or contractual rules.
What matters is that the occurrence is intentional and modeled.
An account should not go negative simply because of a race condition.
Does the ledger need to know the merchant?
Yes, when the platform manages positions for multiple merchants.
Each entry must belong to the correct accounts and must not allow funds to be mixed.
Financial multitenancy requires strict isolation.
How do you prevent incorrect rounding?
Monetary amounts should use exact representations, normally integer units of the smallest currency denomination or suitable decimal types.
Binary floating-point can create accumulated errors.
Percentage rates also need explicit rounding rules.
How do you handle residual cents?
The policy needs to be deterministic.
Divisions, splits, and foreign exchange can produce fractions smaller than the monetary unit.
The system must define who receives the remainder and record the adjustment.
Hiding a difference in rounding is a way to lose reconciliation.
What is a subaccount ledger?
In marketplaces and platforms, each seller or merchant can have its own position.
The ledger allows value to move between internal accounts without relying on immediate bank transfers.
This is useful for splits, commissions, and reserves.
Should payment splitting happen in the ledger?
It can.
A R$ 100 capture can generate R$ 80 for the seller, R$ 15 for another participant, and R$ 5 in fees, according to product rules.
The ledger records these positions in a balanced way.
This is safer than keeping percentages scattered across tables without an explicit financial effect.
The guide to split payments in marketplaces connects this financial memory to allocation by recipient, fees, partial refunds, and payouts, with a complete numerical example.
How does the ledger relate to external settlement?
The ledger represents what the platform believes should happen.
External settlement confirms what actually moved between institutions or accounts.
Reconciliation compares the two.
When there is a difference, the ledger should not be changed arbitrarily to “match”; the cause must be explained and an adjustment recorded when appropriate.
Does a ledger need a public API?
It depends on the product.
Even if customers do not access entries directly, internal services need a stable interface for creating movements and querying balances.
Exposing the ledger database so multiple applications can write freely is risky.
A domain layer helps centralize invariants.
Who can write to the ledger?
Ideally, a small number of authorized components.
Payment, refund, payout, and adjustment services can request movements through a controlled API or queue.
The policy needs to prevent any service from directly running UPDATE on a balance.
Should manual adjustments exist?
Some operations require manual correction.
But an adjustment should be a journal type with a reason, author, approval, and reference.
It should never be a direct UPDATE to the balance.
How do you observe the ledger?
Useful metrics include journals by type, balancing failures, posting latency, blocked duplicates, balance by account, and reconciliation discrepancies.
Alerts should prioritize broken invariants.
A ledger that does not balance is a high-priority incident.
How do you test a ledger?
In addition to case-based tests, use property-based tests.
For any valid event sequence, total debits and credits must balance. A refund cannot exceed eligibility. Duplicating the same event should not duplicate an entry.
Concurrency tests are also essential.
Do the ledger and state machine replace each other?
No.
A state machine controls the lifecycle of objects such as payments and refunds.
The ledger records financial effects.
A payment can move from authorized to captured, and that transition can generate a journal.
The two structures complement each other.
How do you start without building a huge system?
Start with movements that actually change value.
Define the minimum accounts, journals, and invariants. Preserve references to payments and external events. Make balances derivable and prevent entry editing.
Then add new types as the domain grows.
A small, coherent ledger is better than a sophisticated architecture without invariants.
What is the difference between a balance, a transaction, and a movement?
A balance is a position at a given time.
A payment transaction is a business object that goes through a lifecycle such as authorization, capture, and refund.
A ledger movement is the financial effect that changes internal accounts.
Mixing the three creates systems that are difficult to reconcile.
The ledger is the platform's financial memory
Distributed payments generate events over time. A current status does not tell the whole story.
The ledger preserves that history in verifiable movements.
With it, a balance stops being a mysterious number and becomes a demonstrable consequence of captures, fees, refunds, payouts, reserves, and adjustments.
This ability to explain value is one of the differences between a payment integration and mature financial infrastructure.