Wallet choice is useful only when the previous attempt is understood
A second wallet can recover a payment when the first route genuinely failed. It can also create a duplicate payment if the first result is still unresolved.
The decision should therefore be based on payment state, not on customer preference alone.
The three questions to ask before offering another wallet
- Is the invoice still due?
- Is the previous attempt in a final state?
- Is the alternative wallet actually enabled for this merchant and customer context?
If any answer is uncertain, do not create another collection attempt yet.
Preference and authority are different
A customer can prefer Airtel Money, but the merchant still needs a valid, production-enabled Airtel Money route. A PSP advertising the method does not prove that the merchant account is approved for it.
Likewise, a customer can prefer to retry immediately, but the system should block that action when the earlier attempt is still Unknown.
When switching is usually safe
- The earlier attempt has a confirmed cancellation.
- The earlier attempt has expired or timed out with a final provider result.
- The earlier attempt failed for insufficient balance and the customer chooses another enabled wallet.
- The invoice is still unpaid and no other payment has satisfied it.
When switching should be blocked
- The M-PESA Express callback is missing and the CheckoutRequestID has not yet been queried.
- A previous attempt is still pending.
- The customer may have paid through another accepted route.
- The invoice was adjusted, cancelled or already marked paid.
Keep the invoice stable
Wallet switching should create a new payment attempt against the same invoice. It should not create a new bill.
That keeps the commercial record clean and makes it obvious if two payment methods both succeed.
Do not silently move a customer to another wallet
The customer should choose or authorize the alternative method according to the payment rail. A remembered preference can improve UX, but it should not be treated as permission to debit another wallet.
What if the first wallet later succeeds?
If a late success appears after another wallet already settled the invoice, classify it as a duplicate-payment exception. Do not attach the extra money to a future invoice without an explicit merchant policy and customer-facing treatment.
For the full multi-wallet operating model, see the M-PESA + Airtel Money workflow guide. For duplicate-payment protection, see the duplicate-collections guide.
Sources
- Safaricom M-PESA Express Query API: https://developer.safaricom.co.ke/apis/MpesaExpressQuery
- Airtel Africa Developer Portal: https://developers.airtel.africa/
