Integrating a recharge API is technically straightforward: send a request, receive a response. What separates a reliable integration from a frustrating one is how carefully it handles every possible outcome — especially pending transactions, timeouts and retries. Here is a practical guide.
Authentication and security
Use your API key over HTTPS from your server, never from a mobile app or browser. Restrict live keys to your server's IP address, and sign requests with HMAC if the provider supports it. Keep test and live keys separate.
Operators and circles
Fetch the operator list from the API and store operator codes. Use the operator lookup service to detect the operator and circle from a mobile number, so users do not have to choose — and choose wrongly.
Making the request
Send the number, operator, amount and your own unique reference for the transaction. That client reference is crucial: it makes retries safe, because the provider will not create a second recharge for a reference it has already processed.
Handling responses
- Success — store and show the operator reference.
- Failed — show the reason. The amount is refunded to your wallet.
- Pending — the operator has not confirmed yet. Do not retry with a new reference and do not refund yet.
Timeouts
If your request times out, you do not know whether it was processed. Check the status using your client reference, or retry with the same reference — never a new one.
Webhooks
Configure a webhook URL to receive status updates for pending transactions. Verify the signature on every webhook, update your records, respond quickly and handle duplicate deliveries safely.
Your own users' wallets
If you debit your customers' or retailers' wallets, do it in the same database transaction that records the recharge, and refund automatically when a transaction finally fails.
Reconciliation
Compare your transaction records with the provider's reports daily to catch mismatches early.
Testing
Use sandbox keys to test success, failure, pending, insufficient balance and validation errors before going live.
See our mobile recharge API and API documentation.
0 comments