STK push is the easy part. You call the API, the customer gets a prompt, they enter their PIN. Done.
The hard part is the callback. It arrives late, twice, or never. And when it arrives, you have to answer one question: which open invoice does this belong to, and for how much?
This is where payment systems die. Not in the happy path. In reconciliation.
The matching problem
A callback arrives with a transaction ID and an amount. You have a pile of open invoices. The callback doesn't tell you which invoice it pays β you have to figure that out.
If you keyed the STK request to an invoice ID at push time, you have the link. If you didn't, you're guessing from the amount and the phone number, and guessing is how money goes missing.
Rule one: every STK push carries your internal reference from the start. The callback is just the confirmation of something you already tracked.
Partial payments
Invoice for 1000. Callback for 400. The customer paid part of it.
Do not mark the invoice paid.β¦