For a wallet, a payments app or a network of retail shops, mobile recharge looks like an easy feature: take a number, take the money, top up the phone. The request itself is easy. What makes a recharge business work, or quietly lose money, is everything around it: knowing the right operator, showing plans that actually exist, handling the recharges that don't confirm straight away, giving money back when one fails, and matching thousands of transactions at the end of the day.
This guide explains how recharge APIs generally work, for product managers and developers planning an integration. Providers name their fields and endpoints differently, so it describes concepts, not any one provider's API. Your provider's documentation is the reference for the details.
The chain from your app to the operator
A recharge passes through several systems before a plan lands on a phone:
- 1Your app or shopCollects the number, operator, plan and payment
- 2Your backendDebits or holds the customer's money and sends the request
- 3Recharge API providerValidates and forwards the request to the operator's system
- 4Telecom operatorApplies the plan and sends the customer an SMS
- 5Status back to youSuccess, failure or pending, by response, callback or status check
The provider in the middle may connect to operators directly, through other aggregators, or through the Bharat Bill Payment System (BBPS), whose scope under RBI's 2024 Directions includes notices or advice for recharge of prepaid services. For prepaid services on BBPS, the customer's relationship with the biller is validated through the platform rather than by fetching a bill.
A regulatory point to check first
RBI's BBPS Directions say that any entity other than a biller that operates a system for payment of bills outside BBPS is running a payment system that needs RBI authorisation. How that applies to your recharge business depends on how you collect money and from whom. Take legal advice on your model before launch, and ask your provider how its own arrangements are authorised.
Step 1: find the operator and circle
Every recharge needs the operator and the circle (telecom service area) the number belongs to. This is harder than it looks. Under TRAI's mobile number portability rules, people can move their number to another operator anywhere in the country, so the first digits of a number no longer reliably identify its operator.
- Use your provider's operator lookup, if it offers one, rather than guessing from the number prefix.
- Show the detected operator and circle to the customer and let them correct it. A wrong operator is one of the commonest reasons a recharge fails.
- Cache lookups briefly at most. A number can be ported at any time.
Step 2: show plans that exist
Operators change plans often, and a plan that no longer exists will fail. Fetch plans from your provider for the operator and circle, show them with their full details, and refresh your cache regularly.
Under TRAI's consumer protection regulations, every prepaid plan is one of a few voucher types: plan vouchers, top-up vouchers (which add talk-time money with no validity restriction), special tariff vouchers (bundles of data, calls and SMS with a validity of up to 365 days) and combo vouchers. Display the validity and benefits clearly; customers judge a plan on them, not on its name. Our consumer guide to recharging online explains the voucher types in plain terms.
Step 3: take the money before you send
Decide how the customer's money is handled before you send a request, because a recharge can take a while to confirm:
- Wallet or stored balance: debit or place a hold on the amount when you send the request, and release or reverse it only on a final status.
- Direct payment (UPI, card, net banking): send the recharge only after the payment is confirmed by your payment provider's webhook or status check, not by the browser's return.
- Retail networks: agents often hold a prepaid float with you, which you debit per recharge. Keep the float and each debit on a ledger you can reconcile.
Whichever model you use, never send a recharge for money you haven't secured, and never release money for a recharge that's still pending.
Step 4: send the request with your own reference
The recharge request typically carries the mobile number, operator, circle, the plan or amount, and a unique reference generated by your system. That reference is the most important field you send.
- Make it unique per attempt and store it before you send, so you can always look the recharge up later.
- Use it as an idempotency key. If your request times out and you retry, the provider should recognise the same reference and not recharge twice. Confirm how your provider handles duplicate references.
- Save every reference the provider and operator send back: the provider's transaction ID and the operator's reference. Support and reconciliation depend on them.
Step 5: handle the response, including pending
The provider's first response often tells you only that the request was accepted. The final status (success or failure) may come in the same response, or later. Design for three outcomes:
| Status | What it means | What your system should do |
|---|---|---|
| Success | The operator applied the plan; usually comes with an operator reference | Mark the order complete; keep the money; show the customer the confirmation |
| Failure | The operator or provider rejected the recharge, usually with a reason | Release the hold or reverse the debit promptly; show a clear reason |
| Pending | The final answer isn't known yet, often because the operator hasn't responded | Keep the money on hold; tell the customer it's being confirmed; wait for a callback or check status |
Treat the status as a state machine. A pending recharge can move to success or failure; a final status shouldn't be overwritten by a late or duplicate message. If your provider can report a later reversal of a recharge it first reported as successful, agree with it how that's signalled and build a path for it.
Callbacks and status checks
Providers usually notify final statuses by a callback (a webhook) to your server, and offer a status check you can call with your reference. Use both:
- Verify every callback's signature or authentication as your provider documents it, so a forged "success" can't complete an order.
- Make callback handling idempotent: the same callback may arrive more than once.
- Run a scheduled job that checks the status of every recharge still pending after a set time, so a missed callback doesn't leave money on hold.
Our guide to payment gateway webhooks covers signatures, retries and duplicates in depth; the same rules apply to recharge callbacks.
Common failure reasons
Provider error codes differ, but most failures fall into a few groups. Map your provider's codes to groups like these, so your app can show a useful message and your team can spot patterns:
| Group | Typical cause | Handling |
|---|---|---|
| Wrong operator or circle | Number ported, or detection guessed wrong | Ask the customer to confirm and retry |
| Invalid plan or amount | Plan withdrawn or changed | Refresh plans; offer current ones |
| Invalid number | Typo, or not a prepaid number | Ask the customer to check |
| Operator unavailable or timed out | Operator or provider system issue | Wait for the final status; don't resend with a new reference |
| Duplicate request | Same reference sent twice | Look up the original instead |
| Insufficient balance with the provider | Your prepaid float with the provider is low | Top up the float; alert on low balance before it happens |
When the customer has already paid
Failures and pending recharges create customer money questions, and the rules depend on what failed:
- If the customer's payment to you failed after their account was debited, their bank must reverse it under RBI's failed-transaction rules (T + 5 days for UPI and card payments to merchants).
- If the payment succeeded but the recharge failed, you owe the customer a refund. If you collect through a payment aggregator, RBI's rules require refunds to go back to the original payment method unless the customer agrees otherwise.
- If it's pending, tell the customer, and don't encourage a second recharge until it resolves.
Our consumer guide to recharges that failed but took money shows what your customers will be looking for, and is a useful model for your own help pages.
Reconciliation
At the end of each day, three records must agree: your orders, the provider's transaction statement, and the money: customer payments in, refunds out, and debits from your float or settlement with the provider. Match them on your reference and the provider's transaction ID, not on number and amount, because the same customer often recharges the same amount twice.
- Flag recharges you marked successful that the provider reports as failed, and the other way round.
- Flag pending recharges older than your normal window.
- Check every failure has a matching refund or reversal on your side.
- Reconcile your float or prepaid balance with the provider daily.
Our reconciliation guide sets out a daily routine that works for any payment flow.
A test plan before launch
Most providers offer a test environment. Use it to test every outcome, not just success:
| Scenario | Expected behaviour |
|---|---|
| Successful recharge | Order complete once; money kept; confirmation shown |
| Failed recharge | Hold released or debit reversed promptly; reason shown |
| Pending, then success by callback | Order stays pending; completes once on callback |
| Pending, callback never arrives | Scheduled status check resolves it |
| Same callback delivered twice | No double completion or double refund |
| Request times out, retried with the same reference | No second recharge |
| Wrong operator selected | Clear failure; customer can correct and retry |
| Provider float runs low | Alert before recharges start failing |
Questions to ask a recharge API provider
Before choosing one, get clear answers in writing:
- Which operators and circles do you support today, and through which routes?
- How do you detect operator and circle, and how current are your plan lists?
- Which statuses do you return, how quickly do most recharges reach a final status, and how are pending recharges resolved?
- How are callbacks authenticated and retried, and is there a status check by our reference?
- How do you handle duplicate references?
- What's the funding model (prepaid float or settlement), and what reports do we get for reconciliation?
- How are disputes and customer complaints handled, and how fast?
Our recharge page describes LILPE's approach to prepaid mobile and DTH recharge for businesses; confirm current operator coverage and terms during onboarding. For the bill-payment side of the same customers, our explainer on BBPS and Bharat Connect covers how BBPS works for businesses.
Frequently asked questions
What is a mobile recharge API?
An interface that lets an app, website or retail system send prepaid recharge requests to telecom operators through a provider, and receive the result. It usually also offers operator lookup, plan lists, status checks and callbacks.
Why do recharge APIs return a pending status?
Because the operator hasn't confirmed the recharge yet. Pending isn't a failure: keep the customer's money on hold until a callback or status check gives the final result.
How do I avoid double recharges when a request times out?
Send a unique reference with every request and retry with the same reference. Check how your provider treats duplicate references, and look up the original recharge's status before sending anything new.
Do I need RBI authorisation to run a recharge business?
It depends on your model. RBI's BBPS Directions say an entity other than a biller operating a bill payment system outside BBPS needs authorisation. Take legal advice on how you collect and pay out money, and ask your provider how its arrangements are authorised.
Who refunds the customer if a recharge fails after payment?
You do, as the business that took the payment, usually through your payment provider. If you collect through a payment aggregator, the refund must go to the customer's original payment method unless they agree otherwise.
Go deeper
Official sources
- RBI — Master Direction – Bharat Bill Payment System Directions, 2024 (29 Feb 2024)BBPS scope includes notices or advice for recharge of prepaid services; customer relationship validated for prepaid; BBPS reference from initiation; authorisation needed for bill payment systems outside BBPS.
- TRAI — Telecom Consumers Protection Regulations, 2012 (consolidated, 28 Mar 2025)Prepaid voucher types and rules (reg. 4); SMS to the consumer on voucher activation (reg. 6).
- TRAI — Mobile Number Portability FAQs (30 Sep 2024)Numbers can be ported to another operator across the country.
- RBI — Harmonisation of Turn Around Time and customer compensation for failed transactions (20 Sep 2019)Failed UPI and card payments to merchants reversed by T + 5.
- RBI — Reserve Bank of India (Regulation of Payment Aggregators) Directions, 2025Refunds to the original payment method unless the customer agrees otherwise (10(f)).
Last reviewed . Examples, amounts and screens marked illustrative are not LILPE figures.
