Reconciling Transactions Against Gateway Settlement Data

Two sources of truth that will eventually disagree

Every payment system keeps its own internal record of what happened: a transaction created, authorized, captured, maybe refunded. Separately, the gateway or payment provider keeps its own record of what it actually settled — the money that moved, net of fees, on its own schedule. These two records come from different systems, update at different times, and are built for different purposes. Assuming they always agree is the assumption that eventually produces a finance-team fire drill.

On the multi-gateway payment layer our engineers built, reconciliation isn't a manual month-end spreadsheet exercise — it's part of the system. Internal transaction records are matched against provider settlement reports on a scheduled basis, and discrepancies are surfaced automatically rather than discovered when someone finally cross-checks the numbers.

What reconciliation actually catches

In practice, three kinds of discrepancies show up repeatedly:

• Missing settlements — a transaction your system marked as successful never appears in the provider's settlement report, usually because a webhook was missed or a manual status override happened somewhere upstream.
• Amount mismatches — the amount you recorded and the amount actually settled differ, which happens more often than expected once currency conversion, partial captures, and provider fees are in the picture.
• Unexpected fees — the provider deducts something — a chargeback fee, a currency conversion fee, an adjustment — that never generated a corresponding event in your system.

None of these are edge cases in a mature payment system. They're the normal cost of integrating with an external settlement process you don't control. The question isn't whether they'll happen — it's whether you find out from your own reconciliation job or from a customer, an auditor, or an angry finance lead.

Building it into the payment layer, not bolting it on after

Reconciliation works best when it's designed alongside the payment flow, not added after a discrepancy has already caused a problem. That means the internal transaction record needs enough structure from the start — a stable reference ID, the exact amount and currency, the provider and method used — to be matched automatically against a settlement report format that's usually messier and less consistent than either side would like.

It also means refunds, partial refunds, and chargebacks need to update the same internal ledger that reconciliation reads from, so a dispute doesn't quietly desynchronize your records from what actually happened at the provider. This is the same reasoning behind full audit trails on every transaction state change — reconciliation is only as good as the underlying record it's checking.

See how this fits into the rest of the architecture in our payment gateway integration case study, or read more about our payment integration service.