VerveVector — home
← ALL INSIGHTSFIELD GUIDE · M-PESA INTEGRATION

M-Pesa settlement reconciliation, explained

PUBLISHED 2026-10-03 · UPDATED 2026-10-03 · 6 MIN READ

THE DIRECT ANSWER

M-Pesa settlement reconciliation is the process of matching what M-Pesa says happened (callbacks and the M-Pesa statement) against what your system recorded and what reached your bank account. The three regularly disagree — because of timing differences, reversals, transaction fees and duplicate notifications — and the disagreement is precisely where finance teams lose days. Proper reconciliation matches idempotently on Safaricom transaction IDs, closes daily, and routes only genuine exceptions to a human.

Written by Verve Vector, a software engineering studio in Nairobi that builds these systems. Cite at vervevector.digital/insights/mpesa-settlement-reconciliation.

Give us a gig

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.