🗂️

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. For bill payments, relevant categories include: Electricity, Water, Gas, Broadband, Landline, Insurance, Loan Repayment, Education Fees, Municipal Taxes, Cable TV, Fastag, Credit Card, and more.

Response Shape
categories[] → {
          service_name: "Electricity",
          total_operators: 87
          }
        

💡 Store the category names. Use them to populate your biller-selection UI by service type.

Supported BBPS Service Categories (27)

PostpaidPostpaid Bill Payment

ElectricityElectricity Bill Payment

GasGas Bill Payment

WaterWater Bill Payment

LandlineLandline Bill Payment

BroadbandBroadband Bill Payment

InsuranceInsurance Premium Payment

FASTagFASTag Recharge

Gas CylinderGas Cylinder Booking

Cable TVCable TV Bill Payment

Credit CardCredit Card Bill Payment

LoanLoan Repayment

Education FeesEducation Fees Payment

Housing SocietyHousing Society Payment

Municipal TaxesMunicipal Taxes Payment

Clubs & AssociationsClubs & Associations Payment

SubscriptionSubscription

DonationDonation Payment

NCMC RechargeNCMC Recharge

eChallaneChallan Payment

Prepaid MeterPrepaid Meter Recharge

Agent CollectionAgent Collection Payment

RentalRental Payment

Municipal ServicesMunicipal Services Payment

EV RechargeEV Recharge

Fleet CardFleet Card Recharge

NPSNational Pension System

Biller List Setup

GET /api/v2/operator_codes.php

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

Fetch all BBPS billers with their operator codes, active status, and supported amount ranges. Filter by service parameter to get only the billers relevant to your use case.

Response Shape
operators[] → {
          opid: "53",
          name: "MSEDCL Electricity",
          service: "Electricity",
          min_amount: 1,
          max_amount: 50000,
          status: "ACTIVE"
          }
        

💡 Store the full list locally. You will use opid in every bill payment 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 per biller — this is critical for bill payments as it tells you:

Whether the biller supports bill fetch (outstanding amount lookup)
Which additional fields (opt1–opt10) are required (e.g. consumer number, account ID, district)
Supported payment channels and NPCI payment modes

Response Shape
operator → {
          bill_fetch_supported: true, ← drives Step 4 decisionrequired_params: ["consumer_no"], ← maps to opt1–opt10payment_channels: ["NEFT", "IMPS"],
          min_amount: 1,
          max_amount: 50000
          }
        

⚠️ Always check required_params — passing wrong or missing opt fields will cause payment failure.

⚡

Phase 2 — Live Transaction

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

Bill Fetch Optional

GET /api/v2/bills/validation.php

Only if bill_fetch_supported = true in Biller Details (Step 3)

Fetches the outstanding bill amount, due date, and consumer details directly from the biller. Use this to show the customer their exact due amount before payment — improves trust and reduces errors.

Request Parameters

          {
          api_key: "YOUR_API_KEY",
          number: "1234567890", ←
            consumer / account / registered numberamount: 0, ← pass 0 if
            unknownopid: "53", ← from Biller
            List (Step 2)order_id: "FETCH-001", ←
            unique reference for this fetchopt1: "1234567890", ← as
            required by biller (Step 3)mobile: "9876543210"←
            optional
          }
        

Response

          {
          due_amount: 1450.00,
          due_date: "2026-05-15",
          consumer_name: "Vivek Sharma",
          bill_period: "APR-2026"
          }
        

Two paths from here:
Bill fetch supported → show due amount to customer → Step 5
Bill fetch not supported → customer enters amount manually → Step 5

💡 Never skip checking bill_fetch_supported in Biller Details before calling this. Calling it on a non-supported biller returns an error.

Utility Payment (BBPS) Payment

GET /api/v2/bills/payments.php

Submit the bill payment

Submit the bill payment with all confirmed details. This is the payment step — the API processes through the BBPS network and may take variable time.

Request Parameters

          {
          api_key: "YOUR_API_KEY",
          number: "1234567890", ←
            consumer / account numberamount: 1450, ← from fetch
            or manual entryopid: "53", ← from Biller
            List (Step 2)order_id: "ORD-20260506-001", ← unique, never reuseopt1: "1234567890", ←
            consumer number (from Step 3)opt8: "Bills", ← ALWAYS
            "Bills" (fixed, required)refrence_id: "REF-001", ←
            optional reconciliation referencemobile: "9876543210"←
            optional, confirmation SMS
          }
        

⚠️ opt8 must always be set to "Bills" — this is a fixed required value, not optional.
Generate a unique order_id for every transaction. Never reuse one.

Response

          {
          success: true,
          status: "SUCCESS", ←
            "SUCCESS" | "FAILURE" | "PENDING"order_id: "ORD-20260506-001",
          operator_ref: "BBPS123456"← biller'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 60–120 seconds, check via Transaction Status API

💡 If PENDING — use Transaction Status API (/api/v2/status.php) with your order_id to poll. ~99% of transactions complete synchronously with a real-time response.

🔀 Complete Flow Diagram

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

1 Service Category List service-category-list

2 Biller List biller-list → store opids

3 Biller Details (batch) biller-details → bill_fetch flag + opt params

Phase 2 — Live Transaction (per customer bill payment)

Customer selects biller + enters consumer number

Bill fetch decision (from Biller Details)

4 — bill_fetch_supported = true → Bill Fetch → show due amount

or: bill_fetch_supported = false → customer enters amount manually

→ Both paths lead to Step 5

5 Utility Payment (BBPS) opt8="Bills"

Response handling

SUCCESS → update records + notify customer

FAILURE → show failure, do not retry same order_id

PENDING → Transaction Status API (poll, optional)

🔤 opt1–opt10 Field Mapping

BBPS billers require different sets of additional parameters passed as opt1 through opt10. Always refer to required_params from the Biller Details API for each operator.

opt 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 value
`opt9`	Service type / Category
`opt10`	Additional biller-specific field

💡 The exact mapping varies per biller. Use required_params[] from Biller Details as the source of truth.

⚡ 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

Bill Fetch (optional)

bill-fetch

If supported

No cache

Utility Payment (BBPS)

utility-payments

Payment

No cache

Support

📞

Toll Free

18008890016