🗂️

Phase 1 — Setup

Run once during onboarding · Refresh on a schedule · Store results in your DB

Service Category List Setup

POST /api/v2/Service-Category-List.php

Refresh: Weekly or on demand · Rate limit: 10 / day

Fetch all available service categories (Prepaid, DTH, Broadband, Electricity, etc.). Use this to build your service selection UI and know which categories are available.

Response Shape
categories[] → {
          service_name: "Prepaid",
          total_operators: 42
          }
        

💡 Store the category names. Use them to filter the Biller List in the next step.

Biller List Setup

GET /api/v2/operator_codes.php

Refresh: Weekly (changes are rare) · Rate limit: 20 / day

Fetch all billers/operators with their codes, active status, and supported amount ranges. Filter by service=Prepaid or service=DTH to get only relevant operators.

Response Shape
operators[] → {
          opid: "1",
          name: "Jio Prepaid",
          service: "Prepaid",
          min_amount: 10,
          max_amount: 5000,
          status: "ACTIVE"
          }
        

💡 Store the full list locally. You will use opid in every recharge request.

Biller Details Setup

POST /api/v2/operatorFetch.php

Refresh: Weekly (changes are rare) · Rate limit: 20 / day · Supports batch: 53#54#55

Fetch full details for each operator — supported payment channels, NPCI payment modes, bill-fetch support flag, and required extra fields (opt1–opt10).

Response Shape
operator → {
          bill_fetch_supported: true | false,
          payment_channels: ["NEFT", "IMPS"],
          required_params: [] ← maps to opt1–opt10
          }
        

💡 Store per operator. Use bill_fetch_supported to decide if you can show a bill preview.

Circle Codes Setup

GET /api/v2/circle_codes.php

Refresh: Monthly (rarely changes) · Rate limit: 2 / day

Fetch all India telecom circle codes (MH, DL, KA, etc.). Required when fetching recharge plans and initiating prepaid recharges.

Response Shape
circles[] → {
          circle_name: "Maharashtra",
          circle_code: "MH"
          }
        

💡 Cache this locally. It almost never changes.

⚡

Phase 2 — Live Transaction

Run at the time of each customer recharge request · Real-time APIs

Operator & Circle Detect Live

POST /api/v2/operator_fetch_v2.php

Every time a mobile number is entered · MNP + circle-change aware

Pass the customer's 10-digit mobile number. Returns the real-time detected operator and circle, accounting for MNP (Mobile Number Portability) and circle migrations.

Input → Output
// Input
          { number: "9876543210" }

          // Output
          {
          opid: "1",
          operator_name: "Jio",
          circle_code: "MH",
          circle_name: "Maharashtra",
          is_ported: true
          }
        

⚠️ Always call this — never assume operator from number prefix. MNP users will get the wrong recharge otherwise.

Recharge Plan Fetch Optional

POST /api/v2/recharge_plans.php (mobile) | POST /api/v2/DTH_plans.php (DTH)

If you want to show available plans to the customer

Pass the opid (from Step 5) and state_code (from Step 5) to get all available plans for that operator and circle.

Input → Output
// Input
          { opid: "1", state_code: "MH" }

          // Outputplans[] → {
          amount: 299,
          validity: "28 days",
          description: "2GB/day + Unlimited calls",
          type: "Combo"
          }
        

ℹ️ Skipping this step is valid — just let the customer enter an amount directly. Both paths lead to Step 7.

Prepaid / DTH Recharge Payment

GET /api/v2/recharge.php

Submit the recharge

Submit the recharge with all confirmed details. This is the payment step — the API may take variable time depending on the operator.

Request Parameters

          {
          api_key: "YOUR_API_KEY",
          number: "9876543210", ←
            customer mobile / DTH subscriber IDamount: 299, ← from plan or
            manual entryopid: "1", ← from Operator
            Detect (Step 5)state_code: "MH", ← from
            Operator Detect (Step 5)order_id: "ORD-20260506-001"← your unique order ID (never reuse)
          }
        

⚠️ Generate a unique order_id for every transaction. Store it — you may need it for status lookup.

Response

          {
          success: true,
          status: "SUCCESS", ←
            "SUCCESS" | "FAILURE" | "PENDING"order_id: "ORD-20260506-001",
          operator_ref: "JIO123456"←
            operator's transaction reference
          }
        

Status	Action
SUCCESS	Show confirmation to customer, update your records
FAILURE	Show failure message, do not retry with same order_id
PENDING	Wait 30–60 seconds, check via Transaction Status API

Transaction Status Optional

GET /api/v2/status.php

Only if the recharge response was PENDING or ambiguous · ~99% complete synchronously

~99% of transactions return a real-time SUCCESS or FAILURE response directly from the recharge API. Only call this if the response was PENDING, timed out, or unclear.

Input → Output
// Input
          { api_key: "YOUR_API_KEY", order_id: "ORD-20260506-001" }

          // Output
          {
          status: "SUCCESS", ←
            "SUCCESS" | "FAILURE" | "PENDING"operator_ref: "JIO123456"
          }
        

💡 Only call when recharge response is PENDING or unclear. If still PENDING after 3–5 retries — contact KwikAPI support with the order_id.

🔀 Complete Flow Diagram

Phase 1 — Setup (store in DB, refresh weekly/monthly)

1 Service Category List service-category-list

2 Biller List biller-list → store opids

3 Biller Details (batch) biller-details → per operator

4 Circle Codes circle-codes → store circles

Phase 2 — Live Transaction (per customer recharge)

Customer enters mobile number

5 Operator & Circle Detect → opid + state_code

Plan selection (optional)

6a — Show Plans → Recharge Plan Fetch

or: Customer enters amount manually

→ Both paths lead to Step 7

7 Prepaid / DTH Recharge

Response handling

SUCCESS → update records + notify customer

FAILURE → show failure, do not retry same order_id

PENDING → Step 8 Transaction Status (poll, optional)

⚡ Quick Reference

Service Category List

service-category-list

Setup

Cache: Weekly

Biller List

biller-list

Setup

Cache: Weekly

Biller Details

biller-details

Setup

Cache: Weekly

Circle Codes

circle-codes

Setup

Cache: Monthly

Operator & Circle Detect

operator-circle-detect

Per recharge

No cache

Recharge Plans (optional)

mobile-recharge-plans

Per recharge

Short TTL

Prepaid / DTH Recharge

prepaid-dth-recharge

Payment

No cache

Transaction Status (optional)

transaction-status

If PENDING

No cache

Support

📞

Toll Free

18008890016