Most payment integrations are considered done when money moves. The provider returns success, the order is marked paid, the feature ships. What is missing is the part that tells you when your view of reality and the provider’s have come apart — which they will, routinely and for boring reasons.
The gap is normal
Settlement lands a day late. A refund is issued in the provider’s dashboard by someone in support and never reaches your webhook. A chargeback arrives weeks after the original charge. A webhook is delivered twice, or not at all, and your retry hits a provider outage.
None of these are exotic. All of them leave your ledger and the provider’s statement disagreeing. The question is only whether you find out in a day or a quarter.
What reconciliation actually needs
Three things, none of them clever.
A stable external reference on every entry. The provider’s transaction id, stored on the ledger row at the moment you write it. Without this you are matching on amount and timestamp, which is guesswork.
A daily import of the provider’s own record. Their settlement file or API, stored raw and untouched. Not parsed into your schema — raw. When something disagrees you need to see what they actually sent.
A job that compares the two and writes exceptions to a table. Not an email. Not a log line. A row, with a status, that someone can work through and mark resolved.
recon_exceptions
provider_ref
our_amount_minor
their_amount_minor
kind -- missing_ours | missing_theirs | amount_mismatch
status -- open | resolved | accepted
resolved_noteWhy it belongs in the product
A finance person doing this in a spreadsheet is doing it monthly, from a manual export, under time pressure, at the point where the discrepancy is oldest and hardest to explain. The same work done nightly, against yesterday’s data, surfaces a broken webhook the morning after it broke.
The build is about a week. It is the difference between “we think the numbers are right” and being able to show, per day, exactly which ones were not and what was done about them.