API Reference

Complete parameter reference for all 17 KwikAPI endpoints — India Bill Payments & Recharges

UAThttps://uat.kwikapi.com
PRODhttps://www.kwikapi.com
Authapi_key in body (POST) or query (GET)
Fetching APIs
1

Service Category List

Fetch all active service categories available on the platform

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

Use once during setup to populate your UI or sync your local service list. Refresh weekly or when adding new service types.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key

Sample Response

{
  "success": true,
  "status": "SUCCESS",
  "total": 33,
  "categories": [
    { "service_name": "Prepaid", "total_operators": 32 },
    { "service_name": "DTH", "total_operators": 17 },
    { "service_name": "Electricity", "total_operators": 127 }
  ],
  "rate_limit": { "limit": 10, "used": 1, "remaining": 9 }
}
2

Biller List

Fetch all billers with operator codes and service categories

GET 20 / day
GET /api/v2/operator_codes.php

Fetch all active billers. Store locally and refresh weekly. Filter by service to narrow results. Use opid values in all payment and fetch APIs.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
service string Optional Filter by service category (e.g. Prepaid, Electricity, DTH)
page int Optional Page number for pagination (default: 1)

Sample Response

{
  "status": "SUCCESS",
  "response": [
    {
      "operator_name": "Airtel",
      "operator_id": "1",
      "service_type": "Prepaid",
      "status": "1",
      "biller_status": "on",
      "bill_fetch": "NO",
      "supportValidation": "NOT_SUPPORTED",
      "bbps_enabled": "NO",
      "amount_minimum": "10",
      "amount_maximum": "10000"
    }
  ]
}
3

Biller Details

Fetch full details for one or more operators including required fields

POST 20 / day
POST /api/v2/operatorFetch.php

Get deep details for a specific operator. Supports batch lookup — separate multiple opid values with #. The required_params array maps directly to opt1–opt10 fields in payment APIs.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
opid string ✅ Required Operator ID(s). Batch: separate with # (e.g. 53#54#55)
💡
Key fields to store: bill_fetch_supported (drives Bill Fetch decision) and required_params (maps to opt1–opt10 in payment APIs).
4

Circle Codes

Fetch all India telecom circle codes for recharge routing

GET 2 / day
GET /api/v2/circle_codes.php

Fetch all Indian telecom circle codes. Cache locally — this data changes very rarely. Use circle_code values as state_code in Recharge and Recharge Plans APIs.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
⚠️
Rate limit is only 2 / day. Always cache the response and avoid calling this on every page load.
5

Bill Fetch

Fetch outstanding bill amount and consumer details from the biller

GET Per account
GET /api/v2/bills/validation.php

Fetch live bill details before payment. Only call if bill_fetch_supported = true in Biller Details. Displays due amount and consumer name to your user before they confirm payment.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
number string ✅ Required Consumer / account / registered mobile number
amount number Optional Pre-filled amount. Pass 0 if unknown
opid int ✅ Required Operator ID from Biller List API
order_id string ✅ Required Your unique reference ID for this fetch request
opt1–opt10 string Optional Operator-specific fields (see required_params in Biller Details)
mobile string Optional Customer mobile number for SMS confirmation

Sample Response

{
  "status": "SUCCESS",
  "provider": "Jio Postpaid",
  "message": "SUCCESS",
  "due_amount": "1885.00",
  "due_date": "13-07-2025",
  "customer_name": "Anushka Verma",
  "bill_number": "202006005985",
  "bill_date": "28-06-2020",
  "bill_period": "MONTHLY",
  "ref_id": "61936",
  "service": "Postpaid",
  "Additional": ""
}
6

Wallet Balance

Check your KwikAPI merchant wallet balance

GET 48 / day
GET /api/v2/balance.php

Returns your current wallet balance in INR. Check before processing payments to ensure sufficient funds.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key

Sample Response

{
  "response": {
    "balance": "262.80",
    "plan_credit": "1"
  }
}
7

Transaction Status

Check the final status of any payment by your unique order ID

GET 100 / day
GET /api/v2/status.php

Poll this after any payment API if the response is PENDING or unclear. Use your original order_id to look up the transaction.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
order_id string ✅ Required The unique order ID used during the original payment request

Sample Response

{
  "response": {
    "order_id": "11554212",
    "operator_ref": "4162140972233",
    "opr_id": "416214093455",
    "status": "SUCCESS",
    "number": "9876523456",
    "amount": "1",
    "service": "Beneficiary Verification",
    "charged_amount": "2.35",
    "closing_balance": "312.15",
    "available_balance": "0",
    "date": "2024-06-10 14:23:53"
  }
}
Status Meaning
SUCCESS Transaction completed successfully
FAILURE Transaction failed — do not retry with the same order_id
PENDING Still processing — poll again after 30–60 s (max 3–5 retries)
8

Last 100 Transactions

Fetch the latest 100 transactions in reverse chronological order

GET 48 / day
GET /api/v2/transactions.php

Useful for dashboards, reconciliation, and support screens. Returns the most recent 100 transactions.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
9

Operator & Circle Detect

Real-time MNP-aware operator and telecom circle detection

POST Per account
POST /api/v2/operator_fetch_v2.php

Detect real-time operator and telecom circle for any Indian mobile number. Fully MNP-aware — accounts for number portability.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
number string ✅ Required 10-digit Indian mobile number

Sample Response

{
  "success": true,
  "message": null,
  "credit_balance": "499",
  "details": {
    "provider": "VI",
    "opid": "3",
    "circle_code": "17",
    "circle_name": "Bihar (BR)"
  }
}
🚨
Always call this before recharging. Never assume an operator from the number prefix — MNP subscribers will receive wrong recharges otherwise.
10

Mobile Recharge Plans

Fetch all prepaid plans for an operator and telecom circle

POST Per account
POST /api/v2/recharge_plans.php

Fetch available prepaid recharge plans. Use opid and circle_code from Operator & Circle Detect to get the right plan list.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
opid int ✅ Required Operator ID from Operator & Circle Detect API
state_code string ✅ Required Telecom circle code (numeric, e.g. 4 for Maharashtra, 1 for Delhi) from Circle Codes API
11

DTH Recharge Plans

Fetch all available packs for a DTH/D2H operator

POST Per account
POST /api/v2/DTH_plans.php

Fetch all recharge packs available for a DTH operator. Use opid filtered from Biller List with service=DTH.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
opid int ✅ Required DTH operator ID from Biller List API (filter by service=DTH)
12

R-Offer Check

Check active retention / special offers on a prepaid number

POST Per account Airtel & VI only
POST /api/v2/R-OFFER_check.php

Check if a prepaid number has any active R-Offers (retention/special offers). Supported networks: Airtel and VI (Vodafone Idea) only.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
opid int ✅ Required Operator ID — must be Airtel or VI
mobile string ✅ Required 10-digit prepaid mobile number to check offers for
Payment APIs
13

Prepaid / DTH Recharge

Initiate a prepaid mobile, DTH/D2H, or Datacard recharge

GET Per account
GET /api/v2/recharge.php

Initiate a recharge for prepaid mobile, DTH/D2H, or Datacard. Always call Operator & Circle Detect first to get the correct opid and state_code.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
number string ✅ Required Customer mobile number or DTH subscriber ID
amount number ✅ Required Recharge amount in INR
opid int ✅ Required Operator ID from Operator & Circle Detect API
state_code string ✅ Required Telecom circle code from Operator & Circle Detect API
order_id string ✅ Required Your unique order ID — never reuse

Sample Response

{
  "status": "SUCCESS",
  "order_id": "12011070",
  "opr_id": "BRH2512201219430132",
  "balance": "253.18",
  "number": "7070300613",
  "provider": "VI",
  "amount": "10",
  "charged_amount": "9.62",
  "message": "SUCCESS"
}
💡
If status is PENDING, call Transaction Status with your order_id to poll for the final result.
14

Utility Payments (BBPS)

Process any BBPS utility bill payment — 1000+ billers

GET Per account
GET /api/v2/bills/payments.php

Process utility bill payments through the BBPS network — Electricity, Water, Gas, Broadband, Landline, Insurance, Loan EMIs, Education Fees and 1000+ billers.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
number string ✅ Required Consumer / account number
amount number ✅ Required Bill amount in INR
opid int ✅ Required Operator ID from Biller List API
order_id string ✅ Required Your unique order ID — never reuse
opt8 string 🔒 Always "Bills" Must always be "Bills" — fixed required value
opt1–opt7 string Optional Operator-specific fields (see required_params in Biller Details)
opt9–opt10 string Optional Operator-specific fields (see required_params in Biller Details)
refrence_id string Optional Optional reconciliation reference
mobile string Optional Customer mobile number for confirmation SMS
opt1–opt10 Common Mapping
Field Common Usage
opt1 Consumer number / Account number
opt2 Consumer name / Account holder name
opt3 Mobile number / Registered phone
opt4 Email address
opt5 District / Sub-division / Zone
opt6 Bill date / Due date
opt7 Bill number / Reference number
opt8 Always "Bills" (fixed, required)
opt9 Service type / Category
opt10 Additional biller-specific field
⚠️
The exact opt mapping varies per biller. Always use required_params from Biller Details as the source of truth — not this table.
💡
If status is PENDING, call Transaction Status with your order_id to poll for the final result.
15

Payout (Money Transfer)

Initiate a bank account payout via IMPS/NEFT

POST Per account IP Whitelist Required
POST /api/v2/payments/index.php

Initiate a real-money bank transfer to a beneficiary account. Requires IP whitelisting and prior bank account verification.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
account_no string ✅ Required Beneficiary bank account number
amount number ✅ Required Transfer amount in INR
order_id string ✅ Required Your unique order ID — never reuse
ifsc_code string ✅ Required Beneficiary bank IFSC code
bene_name string ✅ Required Beneficiary full name
🚨
IP whitelisting required. Run IP Detect on your production server first, then whitelist that IP in your KwikAPI dashboard before calling this API.
⚠️
Always validate the beneficiary with Bank Account Verification before initiating a payout.
Verification APIs
16

Bank Account Verification

Real-time penny-drop bank account verification with name fetch

POST Per account
POST /api/v2/dmt/account_validate_route2

Verify a bank account in real time using a penny-drop. Returns the registered account holder name. Always call this before initiating a Payout.

Parameter Type Required Description
api_key string ✅ Required Your KwikAPI API key
number string ✅ Required Beneficiary bank account number
account string ✅ Required Same as number (required field alias)
ifsc string Optional IFSC code for faster routing
order_id string ✅ Required Your unique order ID for this verification request

Sample Response

{
  "success": true,
  "status": "SUCCESS",
  "message": "Transfer Success",
  "order_id": "453408",
  "utr": "90391***8811",
  "ben_name": "Anshikha Sonam",
  "charged_amount": "****",
  "date_time": "2019-02-08 12:30:29",
  "verify_status": "VERIFIED"
}
Utility APIs
17

IP Detect

Detect the public IP address of the calling server

GET Unlimited
GET /api/v2/ip_detect.php

Detect the public IP address of your server. Run this on your production server to get the IP to whitelist for all API access. No authentication required.

Parameter Type Required Description
No parameters required

Sample Response

{
  "success": true,
  "message": "Your IP address detected",
  "your_ip": "203.0.113.42",
  "ipv4": "203.0.113.42",
  "ipv6": null
}
Reference Tables

Response Format

All APIs return JSON

All APIs return a JSON body. A successful response always includes "success": true.

Success

{
  "success": true,
  "status": "SUCCESS",
  "message": "..."
}

Failure

{
  "success": false,
  "status": "FAILED",
  "message": "Error detail"
}
Common Error Messages
Message Cause
Invalid API Key Wrong or inactive API key
Rate limit exceeded Too many requests in the allowed window
Insufficient balance Wallet balance too low for the transaction
Order ID already exists Duplicate order_id — must be unique per transaction
IP not whitelisted Server IP not added to whitelist (Payout API)
API MISMATCH Wrong endpoint or parameter combination

Rate Limits Summary

Default daily limits per API key

# API Default Limit
1 Service Category List 10 / day
2 Biller List 20 / day
3 Biller Details 20 / day
4 Circle Codes 2 / day
5 Wallet Balance 48 / day
6 Transaction Status 100 / day
7 Last 100 Transactions 48 / day
8–17 All other APIs Per account (contact support)
💡
Wallet Balance and Transaction Status limits can be increased based on account performance and use case — subject to approval by KwikAPI support.

Code Samples

102 ready-to-use samples across 6 languages

Language Directory
PHP 8+ code-samples/php/
JavaScript Fetch API code-samples/javascript-fetch/
Shell cURL code-samples/curl/
jQuery 3.x AJAX code-samples/jquery/
Axios (Node.js) code-samples/axios/
Python 3 requests code-samples/python/