Why callbacks aren't enough
A successful callback tells your system a payment occurred — that is collection, not accounting. Settlement happens separately: M-Pesa aggregates transactions and settles to your bank account per its schedule, net of fees, and the settlement statement is the document your books must agree with. Between the callback and the settlement sit timing gaps, reversed transactions that cancel earlier ones, tariff fees, and the occasional duplicate notification that a naive system records twice. If your reconciliation is a Monday-morning spreadsheet exercise, every one of those becomes a human investigation.
The four things that break matching
Timing: a transaction confirmed at 23:58 can settle on a different day than your system assumes. Reversals: a reversal is itself a transaction; if your matcher only knows success callbacks, reversals look like money that vanished. Fees: settlement arrives net while your records are gross — the difference must be accounted as fees, not treated as a loss. Duplicates and retries: M-Pesa notifications can repeat; a matcher without idempotency records ghosts. Every credible reconciliation design starts by naming these four and handling each explicitly.
The architecture that works
The pattern we build has five parts. Immutable event log — every callback and every statement row lands once, append-only, before anything else happens. Idempotent matching — transactions join on Safaricom's transaction ID (the TransID on a receipt like SJ84H2KMBQ), with rules that a match is created exactly once regardless of arrival order or duplication. Daily close — each day ends in one of three states: matched, exception, or pending-settlement, and the counts must add up. Exception queue — genuine mismatches (a payment with no order, an order with no settlement line) route to a human queue with full context attached. Audit trail — every automated decision is recorded so that a disputed transaction three weeks later can be reconstructed transaction-by-transaction.
What good looks like, operationally
A healthy reconciliation has three observable properties. The books close daily without heroics — not perfectly, but with every mismatch named and queued. The exception queue trends toward zero and its residue is genuinely exceptional (customer error, fraud attempts, upstream anomalies) rather than ordinary timing noise. And month-end is boring: finance pulls the daily closes, not a fresh investigation. If your current month-end is a spreadsheet archaeology project, that is the signal to instrument the layer underneath it.
Where this fits in a build
Reconciliation is cheapest designed in at integration time and most expensive retrofitted after a year of accumulating edge cases. If you are commissioning M-Pesa work now, ask every bidder one question: show me how a day closes. The answer separates a checkout demo from a payment system — and it is the difference our full commerce tier is built around.
CONTINUE THE THREAD
DEFINITIONS FROM THE LEXICON
Related services: platform engineering & M-Pesa integration · pricing