Jio, Airtel and Vi Recharge API: Operator Codes, Circles and Common Errors

If you are integrating a recharge API, the first day usually goes like this: the request works, the response comes back, and then a few recharges fail for no obvious reason. In most cases the cause is something small, like the wrong operator code or a reused order id.

This post collects the codes and the mistakes in one place.

Mobile operator codes

The full, current list is on the API documentation page. Always check there before going live, because operators occasionally add or change products.

DTH operator codes

What the circle code is for

The circle tells the system which telecom region the number belongs to. It is optional in the A1Topup API, but sending the right circle helps with plan lookups and avoids edge cases. If you do not want to ask users, the operator detection API returns both the operator and the circle from the mobile number.

The mistakes behind most failed recharges

1. Wrong operator code. A Jio number sent with the Airtel code fails. Detect the operator automatically instead of trusting a dropdown.
2. BSNL top-up vs STV. BT and BR are different products. Sending a special tariff amount as a top-up fails.
3. Reused order id. Every request needs a new order id. Reusing one makes the API treat it as a duplicate.
4. Retrying a pending recharge. Pending is not failed. Retrying creates a second recharge if the first one succeeds later.
5. Amount not valid for the operator. Some operators accept only specific plan amounts. Show live plans with the recharge plan API.

A safe request flow

1. Detect operator and circle from the number.
2. Show valid plans for that operator.
3. Create a new order id and send the recharge.
4. Read the status; if pending, wait for the callback or check the status API with the same order id.

Conclusion

Getting codes and order ids right removes most integration headaches. Keep the documentation open while you build, and test every operator with a small amount before going live.