---
title: "BBPS — Pay a Utility Bill — API Recipe"
description: "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."
canonical: "https://eps.eko.in/recipe/bbps-bill-payment"
---


> **Canonical URL:** https://eps.eko.in/recipe/bbps-bill-payment
> This is a machine-readable Markdown version of the page for AI agents and LLMs. The primary (HTML) version lives at the canonical URL above.

# BBPS — Pay a Utility Bill — API Recipe

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 details: [Bharat Bill Payment System (BBPS)](https://eps.eko.in/products/bbps-api.md)

## Flow

```mermaid
flowchart TD
  s1["GET Get BBPS Categories"]
  s2["GET Get BBPS Operators"]
  s3["GET Get Operator Parameters"]
  s4["GET Fetch BBPS Bill"]
  s5["POST Pay BBPS Bill"]
  s6["GET Transaction Inquiry"]
  done(["done"])
  s1 -->|"response_type_id 2457: Categories returned — list the billers in the chosen category."| s2
  s2 -->|"response_type_id 2461: Billers returned — read the chosen operator's input fields."| s3
  s3 --> s4
  s4 -->|"response_type_id 1052: Bill fetched — pay the exact amount returned."| s5
  s5 -->|"status 0"| done
  s5 -->|"response_type_id 208: Amount mismatch — re-fetch the bill and retry with a fresh client_ref_id."| s4
  s5 --> s6
  s6 -->|"status 0"| done
```

## Steps

1. `GET` **[Get BBPS Categories](https://eps.eko.in/docs/bbps-get-categories.md)** — 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` → go to step 2 (Get BBPS Operators). Categories returned — list the billers in the chosen category.
2. `GET` **[Get BBPS Operators](https://eps.eko.in/docs/bbps-get-operators.md)** — 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` → go to step 3 (Get Operator Parameters). Billers returned — read the chosen operator's input fields.
3. `GET` **[Get Operator Parameters](https://eps.eko.in/docs/bbps-get-operator-parameters.md)** — 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. `GET` **[Fetch BBPS Bill](https://eps.eko.in/docs/bbps-fetch-bill.md)** — 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` → go to step 5 (Pay BBPS Bill). Bill fetched — pay the exact amount returned.
5. `POST` **[Pay BBPS Bill](https://eps.eko.in/docs/bbps-pay-bill.md)** — 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` → go to step 4 (Fetch BBPS Bill). Amount mismatch — re-fetch the bill and retry with a fresh client_ref_id.
6. `GET` **[Transaction Inquiry](https://eps.eko.in/docs/transaction-inquiry.md)** — 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.

## Notes

- Call the steps in the order shown above; each links to its full API reference.
- Branch on the exact field each step names above: `response_type_id` says which response shape came back (the usual routing key), while `status` is the envelope's success flag — `0` is success, anything else is a failure.
- All requests are signed; see [How Auth Works](https://eps.eko.in/docs/how-auth-works).