Indian Prepaid Recharge Plans AI Agent / LLM

# Indian Prepaid Recharge Plans API — Way2API®

- **Endpoint:** `POST https://app.way2api.com/api/v1/mobile/recharge-plans`
- **Auth:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`)
- **Content-Type:** `application/json`
- **Category:** Telecom
- **Availability:** Available in India
- **Docs:** https://app.way2api.com/documentation/mobile-recharge-plans

## What it does

Indian Prepaid Recharge Plans API — Get every prepaid recharge plan an Indian mobile operator currently sells in one telecom circle, for Airtel, Jio, Vi (Vodafone Idea) and BSNL. Each plan comes back with its amount in rupees, its validity in one consistent readable form (plus validity_days whenever the validity is a fixed number of days), the operator's own benefit description and a status saying whether it is still on sale. Every plan also carries a stable category — popular, unlimited, data, topup, voice, roaming, entertainment and more — that does not change when an operator renames its own sections, with the operator's section name kept beside it as category_label for display. When the customer does not know their operator or circle, look them up first from the mobile number with the Operator and Circle Check API.

## Request body (application/json)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `operator` | string | yes | Prepaid operator. Accepted values: airtel, jio, vi (Vodafone Idea), bsnl. Case, spaces and punctuation are ignored, and common alternative names such as reliance_jio, vodafone, idea and vodafone_idea are accepted. |
| `circle` | string | yes | Telecom circle. Accepted values: andhra_pradesh, assam, bihar, chennai, delhi, gujarat, haryana, himachal_pradesh, jammu_kashmir, karnataka, kerala, kolkata, madhya_pradesh, maharashtra, mumbai, north_east, odisha, punjab, rajasthan, tamil_nadu, up_east, up_west, west_bengal. Case, spaces and punctuation are ignored ("UP (East)" and "J&K" both work), and a state that shares a circle resolves to that circle: goa to maharashtra, telangana to andhra_pradesh, jharkhand to bihar, chhattisgarh to madhya_pradesh, uttarakhand to up_west, sikkim to west_bengal and the north-eastern states to north_east. |

## Example request

```bash
curl -X POST https://app.way2api.com/api/v1/mobile/recharge-plans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operator":"airtel","circle":"karnataka"}'
```

## Success response — 200

```json
{
    "status": "SUCCESS",
    "status_code": 200,
    "charged": true,
    "success": true,
    "message": "",
    "message_code": "OK",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "result": {
            "operator": "airtel",
            "circle": "karnataka",
            "plan_count": 4,
            "plans": [
                {
                    "category": "popular",
                    "category_label": "Trending Packs",
                    "amount": 399,
                    "validity": "28 days",
                    "validity_days": 28,
                    "description": "Calls : Unlimited | Data : Unlimited 5G + 2.5GB/day | SMS : 100/day | COMBO : 28 days",
                    "status": "active"
                },
                {
                    "category": "unlimited",
                    "category_label": "Unlimited 5G Plans",
                    "amount": 429,
                    "validity": "1 month",
                    "validity_days": null,
                    "description": "Calls : Unlimited local STD & Roaming | Data : Unlimited 5G + 2.5GB/day | SMS : 100/Day",
                    "status": "active"
                },
                {
                    "category": "data",
                    "category_label": "Data",
                    "amount": 77,
                    "validity": "7 days",
                    "validity_days": 7,
                    "description": "Data: 5GB | COMBO: 7 days",
                    "status": "active"
                },
                {
                    "category": "topup",
                    "category_label": "TOPUP (top up voucher)",
                    "amount": 500,
                    "validity": "",
                    "validity_days": null,
                    "description": "TOPUP : 423.73",
                    "status": "active"
                }
            ]
        }
    }
}
```

## Error response — 400

```json
{
    "status": "FAILED",
    "status_code": 400,
    "charged": false,
    "success": false,
    "message": "Recharge plans could not be fetched for this operator and circle right now. Please try again shortly.",
    "message_code": "REQUEST_FAILED",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "error_code": "VENDOR_ERROR"
    }
}
```

## Integration rules

- Every response is JSON carrying `status`, `status_code`, `charged`, `success`, `message`, `message_code` and (once a call reaches the provider) `order_id`. The verification payload is under `data.result`.
- `charged` (boolean) is the authority on billing. Do NOT infer it from the HTTP status: `422` is returned both for input we rejected (not charged) and for a lookup the provider ran and billed us for that returned a negative result (charged).
- `message_code` is a fixed vocabulary — branch on it instead of parsing `message`. Values: `OK`, `ACCEPTED`, `PROVIDER_NO_RESPONSE`, `VERIFICATION_FAILED`, `NO_RECORD_FOUND`, `INVALID_INPUT`, `REQUEST_FAILED`, `MISSING_API_KEY`, `INVALID_API_KEY`, `INSUFFICIENT_BALANCE`, `NO_API_ACCESS`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `PROVIDER_UNAVAILABLE`.
- `success` reports the verification outcome; `status` reports the ORDER lifecycle (`SUCCESS`/`PENDING`/`FAILED`). They differ on a charged negative result: the order completed and was billed while the verification did not pass.
- A failed verification is still a successful HTTP call — the outcome lives in the response body, so do not treat `200` as "verified".
- Status codes: `200` result returned, `202` pending or provider did not respond (both charged — quote the `order_id`), `401` missing/invalid key, `402` insufficient balance, `403` no access to this service, `422` see `charged`, `429` rate limited (honour the `Retry-After` header), `503` temporarily unavailable.
- Rate limits are per API key, per service, on a 1-minute sliding window.
- Load the API key from an environment variable or secret store. Never hard-code it, never commit it, and never ship it in client-side code — calls must be made from your backend.