GETFetch BBPS Bill

Retrieve outstanding bill details from a biller before processing payment.

GET/customer/payment/bbps/bill

Retrieves the live bill amount and customer name for a biller. Call this before Pay Bill so the agent can confirm the amount with the customer.

Carry amount and utilitycustomername from this response into Pay Bill, and use the same client_ref_id for the matching Pay Bill call. Paying anything other than the fetched amount is rejected with status 208.

Parameters vary by operator. The fields listed below are the common set — call Get Operator Parameters first and treat its list_elements as the source of truth. Every additional param_name it returns must be sent here and to Pay Bill, with the same values in both.

Note that response_status_id is -1 on success for this endpoint. Branch on status and response_type_id, never on response_status_id.

Tip

This endpoint is one step in a complete workflow:

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.

Request

Query parameters

Field	Type	Required	Description
`initiator_id`	string	required	Registered mobile number of the API user (see Platform Credentials).e.g. 9962981729
`phone_operator_code`	string	required	Biller identifier — the `operator_id` from the Get Operators response.e.g. 53
`utility_acc_no`	string	required	Bill / account number for the biller.e.g. 3287820071
`confirmation_mobile_no`	string	required	Customer mobile number linked with the bill.e.g. 9903457748
`sender_name`	string	required	Customer name.e.g. Asaad
`category`	number	required	The `operator_category_id` from Get Categories (e.g. `8` = Electricity).e.g. 8
`client_ref_id`	string	required	Unique partner reference for this request. Reuse the same value on the matching Pay Bill call; use a fresh one for every new payment attempt.e.g. 2026010100123456789
`source_ip`	string	required	Originating client IP address.e.g. 192.168.1.1
`district_discome`	string	optional	District-level distribution company code. Required for operator 190 (UPPCL) only — resolve it via the District Discome endpoint.e.g. Lucknow-MVVNL
`state`	string	optional	State code, where the operator requires it.e.g. 1

initiator_idstringRequired

Registered mobile number of the API user (see Platform Credentials).

example: 9962981729

phone_operator_codestringRequired

Biller identifier — the `operator_id` from the Get Operators response.

example: 53

utility_acc_nostringRequired

Bill / account number for the biller.

example: 3287820071

confirmation_mobile_nostringRequired

Customer mobile number linked with the bill.

example: 9903457748

sender_namestringRequired

Customer name.

example: Asaad

categorynumberRequired

The `operator_category_id` from Get Categories (e.g. `8` = Electricity).

example: 8

client_ref_idstringRequired

Unique partner reference for this request. Reuse the same value on the matching Pay Bill call; use a fresh one for every new payment attempt.

example: 2026010100123456789

source_ipstringRequired

Originating client IP address.

example: 192.168.1.1

district_discomestringoptional

District-level distribution company code. Required for **operator 190 (UPPCL) only** — resolve it via the District Discome endpoint.

example: Lucknow-MVVNL

statestringoptional

State code, where the operator requires it.

example: 1

These headers authenticate and sign every request. See How Auth Works for details.

Field	Type	Required	Description
`developer_key`	string	required	Static API key issued to your account after KYC.
`secret-key`	string	required	Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).
`secret-key-timestamp`	string	required	Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.
`content-type`	string	required	application/jsone.g. application/json

developer_keystringRequired

Static API key issued to your account after KYC.

secret-keystringRequired

Dynamic per-request signature: base64(HMAC-SHA256(timestamp, base64(access_key))).

secret-key-timestampstringRequired

Current time in milliseconds since UNIX epoch, used to compute secret-key. Must match server time.

content-typestringRequired

application/json

example: application/json

Response types

response_type_id	Meaning	Next step
`1052`	Bill fetched — confirm the amount with the customer, then pay it.	Pay BBPS Bill
`1468`	Bill fetch failed. Verify the account details and retry after some time — do not proceed to payment.	—

Responses

1052Bill fetched — confirm the amount with the customer, then pay it.Next:Pay BBPS Bill

statusnumber
Primary success indicator (0 = success).
messagestring
Human-readable response / error message.
response_status_idnumber
Granular status id; see the shared error-codes table.
response_type_idnumber
A unique id for every possible response shape (success or error) — useful for client logic branching and analytics.
dataobject
API-specific response payload.
- amountstring
  Bill amount due, in rupees. Present this to the customer and send the exact same value to Pay Bill.
- utilitycustomernamestring
  Customer name on the bill. Echo this back as `utilitycustomername` on Pay Bill.
- billDueDatestring
  Due date in `YYYYMMDD` format.
- customer_idstring
  Account / consumer number resolved by the biller.
- billdatestring
  Date the bill was generated, where the biller returns it.
- billernamestring
  Biller name, where provided.
- bbpstrxnrefidstring
  BBPS transaction reference, where provided.
- billDetailsListarray
  Additional bill line items, where the biller returns them.
- ifsc_statusnumber
  Biller-side status flag.
- user_codestring
  Agent's user code.

Next steps

NextPOSTPay BBPS BillProcess a bill payment or recharge for any BBPS-connected biller.

Request

Query parameters

Response types

Responses

Next steps

Related