BBPS — Pay a Utility Bill

Pick a biller by category, read the fields it requires, fetch the live bill, then pay the exact amount. Get Locations is an optional extra filter on the biller list, and UPPCL (operator 190) additionally needs a district_discome from Get District Discome — neither is a step here because neither applies to every biller.

Product & pricing: Bharat Bill Payment System (BBPS)

1. 1
   GETGet BBPS Categories

   List the biller categories and let the agent pick one. The `operator_category_id` chosen here filters the biller list, and is also the `category` param on Fetch Bill and Pay Bill. Do not hard-code these ids — the live list is authoritative.

   If response_type_id is 2457 — skip to step 2, Get BBPS Operators. Categories returned — list the billers in the chosen category.

2. 2
   GETGet BBPS Operators

   List the billers, filtered by the chosen `category` (and optionally by `location` from Get Locations). Note the rename: the `operator_id` returned here is sent as `phone_operator_code` to Fetch Bill and Pay Bill.

   If response_type_id is 2461 — skip to step 3, Get Operator Parameters. Billers returned — read the chosen operator's input fields.

3. 3
   GETGet Operator Parameters

   Read the fields this operator requires and render the bill-entry form from them. `list_elements` is the source of truth: every `param_name` it returns must be sent to BOTH the next step and Pay Bill, with identical values. For operator 190 (UPPCL) only, also resolve `district_discome` via Get District Discome before continuing.

4. 4
   GETFetch BBPS Bill

   Fetch the live bill and show the customer the amount and due date. Carry `amount` and `utilitycustomername` into the payment, and reuse this call's `client_ref_id` for it. `response_status_id` is `-1` on success here — branch on `response_type_id`, not on it. On `1468` the bill could not be fetched: verify the account details, retry later, and do not pay.

   If response_type_id is 1052 — skip to step 5, Pay BBPS Bill. Bill fetched — pay the exact amount returned.

5. 5
   POSTPay BBPS Bill

   Pay the exact amount returned by Fetch Bill, echoing back `utilitycustomername`. The only money-debit step — persist `tid` and your `client_ref_id` before any retry. A `208` means the amount did not match: re-fetch the bill and retry with a FRESH `client_ref_id` (one reference identifies one payment attempt and must never be reused across retries); a `tid` is returned even on `208`, so store it first.

   If status is 0 — the flow is complete.

   If response_type_id is 208 — skip to step 4, Fetch BBPS Bill. Amount mismatch — re-fetch the bill and retry with a fresh client_ref_id.

6. 6
   GETTransaction Inquiry

   Reconciliation only, not a mandatory leg — the previous step already completes the flow on success. This is the generic Transaction Inquiry endpoint, shared across every product. Use it when the Pay Bill response timed out or came back awaited: inquire by `tid`, or by your `client_ref_id` if you never received the `tid`. A timeout is never an automatic failure.

   If status is 0 — the flow is complete.

Flow at a glance