Reconciliation is the part of a payment system that nobody specifies and everybody eventually needs.
The pattern is consistent. A business integrates a payment provider, transactions flow, everything appears fine. Some months later somebody asks whether the money actually received matches what the system says was collected, and the honest answer is that nobody knows, because nothing has ever checked.
By then the discrepancies have been accumulating silently, and reconstructing the correct position is far more expensive than continuous checking would have been.
What breaks without it
Provider fees are not what you modelled. Small per-transaction differences compound invisibly across volume.
Refunds and chargebacks go unrecorded. Money leaves without a corresponding entry, so the ledger drifts steadily out of true.
Payments succeed on the provider side and fail to record locally. Network timeouts guarantee this happens; the only question is how often and whether you notice.
Settlement timing hides gaps. Providers settle in batches on their own schedule, so a naive daily comparison shows differences that are timing rather than error, and real errors get lost in the noise.
Multi-currency introduces drift. Rates at authorisation, capture and settlement all differ, and if the system does not record which was applied when, the gap cannot be explained afterwards.
How we build it
The ledger is the source of truth, and it is append-only
Balances are derived from immutable entries rather than stored as a mutable figure. Corrections are appended as reversing entries, never overwrites. This is what makes the question “why is this balance what it is?” answerable with a query instead of an archaeology exercise across application logs.
Amounts are integer minor units with explicit currency throughout. Binary floating point cannot represent most decimal fractions exactly, and the error is invisible in any single calculation while accumulating across a settlement run.
Provider files are ingested, not read
Settlement files are pulled on a schedule, parsed into the same canonical shape regardless of provider format, and stored as received. Keeping the raw file matters: when a discrepancy surfaces weeks later, you need what the provider actually sent, not your interpretation of it.
Matching runs in tiers
Exact match on provider reference handles most volume. Amount and date matching within a tolerance window catches timing differences. What remains after both is a genuine exception, and the volume of exceptions is small enough for a person to work.
The tolerance window is a business decision expressed as configuration, not a constant buried in code.
Exceptions are a workflow, not a report
An unmatched transaction goes into a queue with the context needed to resolve it, an owner, and a state. Resolving it records what was decided and why. A reconciliation system that produces a list of problems nobody is accountable for is a reconciliation system that gets ignored by the second week.
Idempotency prevents the problem upstream
Much of what reconciliation catches is duplicate processing that should never have happened. Payment endpoints get called twice as a matter of routine, through client retries, load balancer retries and provider webhook redelivery. Getting exactly-once right at the point of capture reduces what reconciliation has to clean up afterwards.
What you end up with
A daily answer to whether your books match reality, an auditable trail behind every figure, and exceptions surfaced while they are still small enough to explain.