What to get right before you integrate mobile money

A mobile money payment looks easy in a demo: send a request, the customer approves on their phone, and you get a callback. In production, that simple flow fails in ways a card integration rarely does, and each failure involves somebody's real money.

These are the design decisions we settle before writing the first line of integration code.

Treat every payment as a state machine

The customer may approve in five seconds, in four minutes, or not at all. Your request can time out on your side while still succeeding on the provider's side. A success or failure flag cannot describe that, so give each payment explicit states.

created -> requested -> pending -> succeeded
                              -> failed
                              -> expired
                              -> unknown  (needs a status check)

The important state is unknown. When your request times out, you do not know what happened. Do not mark the payment as failed and do not let the customer simply retry. Check the status with the provider first.

Make everything idempotent

Callbacks can arrive twice, or arrive before your own request has returned. Your handler should reach the same result no matter how many times it runs.

• Create your own reference before calling the provider, and store it first.
• Put a unique database constraint on the provider's transaction ID.
• Update the balance and the payment state in one database transaction.
• Verify the callback's authenticity, then confirm the result with a server-side status check before giving value.

Do not rely on callbacks alone

Callbacks get lost. Run a background job that looks for payments stuck in pending or unknown and asks the provider for their status. Without it, you will have customers who paid and received nothing, and you will only hear about it from them.

Reconcile every day

Compare the provider's statement against your ledger automatically, every day. Report three lists: in both but with different amounts, only on the provider's side, and only on yours. Small differences found the next morning are easy to fix. The same differences found at month end are not.

Design the waiting screen

Most support tickets begin at the moment a customer is staring at a screen wondering whether the money left. Tell them plainly to check their phone for a prompt. Show a live status. Give them a reference. And tell them what to do if the money left their account but the screen says it failed.

A short checklist

• An explicit state for every payment, including unknown
• Idempotent handlers with database-level uniqueness
• A background job that resolves stuck payments
• Daily automated reconciliation
• A double-entry ledger, not a single balance column
• An alert when the success rate drops