Handling Mobile Money Payment Failures: Timeouts, Retries, Idempotency and Recovery

On a Senegalese site, a significant share of mobile money payment attempts does not succeed on the first try. Insufficient balance, wrong PIN, push never seen, network dropping: these failures are normal. What separates a merchant who loses sales from one who recovers them is how they handle the aftermath of failure.

This guide covers the real causes of failures, how to handle timeouts and retries technically without ever double-debiting, and how to recover the customer and reconcile your transactions to turn a failure into a sale.

Why a mobile money payment fails

Before fixing, you must understand. Failures fall into a few families.

Customer-side failures

The most frequent: insufficient balance. In Senegal, many Orange Money or Wave accounts run tight, and a 25,000 FCFA cart exceeds what is left. Next come the wrong PIN, voluntary cancellation, and the never-validated push because the customer left the page or did not see the notification.

Network failures

The USSD push does not arrive, or the confirmation is lost between the operator and the aggregator. The customer may have paid, but your server does not know it yet. This is the most dangerous case because it creates uncertainty.

Technical failures

Expired API key, misconfigured webhook, server-side timeout too short, or a poorly recorded order that prevents matching. These are on your side and entirely avoidable.

Timeouts: how long to wait

A mobile money payment is asynchronous. The customer receives a push and may take one, two, even three minutes to enter their PIN, especially on an old phone. If your server gives up after 30 seconds, you declare a failure while the customer is in the middle of paying.

Practical rule

Keep the validation window open longer than your intuition suggests. A delay on the order of two to three minutes before marking a transaction "expired" is reasonable for the Senegalese context. During this time, show the customer a clear waiting message: "Validate the payment on your phone."

Never close on a timeout without checking

Before declaring a definitive failure, query the aggregator about the real status of the transaction (status verification endpoint). The customer may have paid after your timeout. This check avoids the nightmare scenario: customer debited, order marked failed.

Retries and idempotency: never debit twice

When a payment fails, the customer often retries. And your system may also be tempted to retry automatically. Without precautions, you risk debiting twice.

The idempotency key

For each payment attempt, generate a unique identifier (idempotency key) and send it to the aggregator. If the same request arrives twice with the same key, the aggregator processes it only once. This is your protection against double clicks and automatic retries.

Idempotent webhooks

Aggregators sometimes resend the same webhook several times to make delivery reliable. Your back end must detect that a transaction is already processed and ignore duplicates. Store the status and check it before any processing.

Smart retry, not blind retry

Do not automatically retry a payment declined for insufficient balance: it will fail again. On the other hand, a network failure (timeout) may justify a new attempt after status verification. Distinguish failure types before deciding.

Recovering the customer: winning back the cart

A failure is not a lost sale, it is a paused sale. The cart abandoned on a payment failure is one of the most recoverable, because the customer wanted to buy.

The right channel: WhatsApp

In Senegal, WhatsApp is the most effective recovery channel. A simple, personalized message sent within the hour: "Hello, your order for [product] could not be validated. Here is a link to retry." The recovery rate is clearly higher than email.

The right timing

Recover fast. The longer you wait, the more the intent evaporates. A first follow-up within the hour, a second the next day if no response. Beyond that, you tire the customer.

Adapt the message to the cause

If the failure was insufficient balance, offer installment payment or an adjusted amount. If it was a timeout, reassure: "No debit occurred, you can safely retry." A generic message converts less than one that addresses the real reason.

Reconciliation: matching money to orders

Reconciliation means verifying that every franc collected matches an order, and that every paid order actually received its money. It is tedious and it is vital.

The classic mismatch

Webhooks can arrive late, in duplicate, or get lost. The result: paid orders marked "pending", or the reverse. Without reconciliation, you ship unpaid products or leave customers who paid without an order.

How to reconcile

At least once a day, retrieve the list of successful transactions on the aggregator side and compare it to your orders. Any divergence is handled manually: order paid but pending, you unblock it; order marked paid without a transaction, you investigate.

Customer mini case: an online bookstore in Thies

An online bookstore in Thies was losing about 30% of orders on payment failure, with no recovery. After analysis, two thirds of these failures were insufficient balances or timeouts, meaning customers who genuinely wanted to buy.

We put three things in place: a systematic status check after timeout (which saved payments already made but unconfirmed), an automatic WhatsApp follow-up within the hour with a resume link, and daily reconciliation. In six weeks, the recovery rate on initially failed orders went from almost zero to 41%. No new acquisition, just better failure handling.

Reducing failures at the source

Recovering is good, preventing is better.

• Show the amount clearly before validation to avoid balance surprises.
• Offer several operators: a customer with no Orange Money balance may have Wave.
• Give visible instructions: "Validate the push on your phone, do not close this page."
• Test all flows in the sandbox before production.

FAQ

What is the leading cause of mobile money payment failure in Senegal?

Insufficient balance, followed by the never-validated push (customer leaving the page) and network timeouts. These are mostly failures recoverable through a follow-up.

How long should I wait before declaring a payment failed?

Allow two to three minutes for validation, then query the aggregator for the real status before concluding a failure. The customer may have paid after your delay.

How do I avoid debiting a customer twice?

Use an idempotency key per attempt and make your webhooks idempotent by storing and checking the status of each transaction before processing.

Should I automatically retry a declined payment?

Not a decline for insufficient balance, it will fail again. A retry makes sense after a network timeout, and only after verifying the real status on the aggregator side.

How often should I reconcile my payments?

At least once a day. Compare the aggregator's list of successful transactions with your orders to catch lost or duplicate webhooks before shipping.

Let's talk about your project. Losing sales on avoidable payment failures? Let's discuss on WhatsApp +221 77 596 93 33.