---
title: "Fetch BBPS Bill API Reference"
description: "Retrieve outstanding bill details from a biller before processing payment."
canonical: "https://eps.eko.in/docs/bbps-fetch-bill"
---


> **Canonical URL:** https://eps.eko.in/docs/bbps-fetch-bill
> 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.

# Fetch BBPS Bill API Reference

`GET https://staging.eko.in/ekoapi/v3/customer/payment/bbps/bill`

Retrieve outstanding bill details from a biller before processing payment.

**Behaviour**

- **Read-only**: Changes nothing; only returns data.

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`.

> View product & pricing details: [Bharat Bill Payment System (BBPS)](https://eps.eko.in/products/bbps-api.md)

## Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| initiator_id | string | yes | Registered mobile number of the API user (see Platform Credentials). e.g. 9962981729 |
| phone_operator_code | string | yes | Biller identifier — the `operator_id` from the Get Operators response. e.g. 53 |
| utility_acc_no | string | yes | Bill/account number. For a prepaid recharge, the customer's mobile number. e.g. 3287820071 |
| confirmation_mobile_no | string | yes | Customer's alternate mobile number. This is only used for sending the confirmation SMS. It may be same as the `utility_acc_no` for prepaid recharges. e.g. 9903457748 |
| sender_name | string | yes | Customer name. e.g. Asaad |
| category | number | yes | The `operator_category_id` from Get Categories (e.g. `8` = Electricity). e.g. 8 |
| client_ref_id | string | yes | 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 | yes | Originating client IP address. e.g. 192.168.1.1 |
| district_discome | string | no | District-level distribution company code. Required for **operator 190 (UPPCL) only** — resolve it via the District Discome endpoint. e.g. Lucknow-MVVNL |
| state | string | no | State code, where the operator requires it. e.g. 1 |
| communication | number | no | Payment mode: `0` (default) = online — instant settlement, lower commission. `1` = offline — higher commission, but the bill takes a minimum of 6 working hours to settle. Pass the same value to Pay Bill. e.g. 0 |

## Headers

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

## Response

⭐ marks fields highlighted as verifiable.

| Field | Type | Description |
| --- | --- | --- |
| status | number | Primary success indicator (0 = success). |
| message | string | Human-readable response / error message. |
| response_status_id | number | UI display hint only (-1/0 success, 1 failure, 2 initiated, 3 refund initiated, 4 refunded). Never branch on it — use `status` (and `tx_status` for financial APIs), or `response_type_id` where documented. |
| response_type_id | number | A unique id for every possible response shape (success or error) — useful for client logic branching and analytics. |
| data | object | API-specific response payload. |
| data.amount ⭐ | string | Bill amount due, in rupees. Present this to the customer and send the exact same value to Pay Bill. |
| data.utilitycustomername ⭐ | string | Customer name on the bill. Echo this back as `utilitycustomername` on Pay Bill. |
| data.billDueDate ⭐ | string | Due date in `YYYYMMDD` format. |
| data.customer_id ⭐ | string | Account / consumer number resolved by the biller. |
| data.billdate | string | Date the bill was generated, where the biller returns it. |
| data.billername | string | Biller name, where provided. |
| data.bbpstrxnrefid | string | BBPS transaction reference, where provided. |
| data.billDetailsList | array | Additional bill line items, where the biller returns them. |
| data.ifsc_status | number | Biller-side status flag. |
| data.user_code | string | Agent's user code. |

## Response types

Branch on `response_type_id` to decide the next call:

| response_type_id | Meaning | Next step |
| --- | --- | --- |
| 1052 | Bill fetched — confirm the amount with the customer, then pay it. | [bbps-pay-bill](https://eps.eko.in/docs/bbps-pay-bill.md) |
| 1468 | Bill fetch failed. Verify the account details and retry after some time — do not proceed to payment. | — |

## Example response

`response_type_id` `1052` — Bill fetched — confirm the amount with the customer, then pay it.. Next step: [bbps-pay-bill](https://eps.eko.in/docs/bbps-pay-bill.md).

```json
{
  "response_status_id": -1,
  "data": {
    "amount": "2870.0",
    "utilitycustomername": "Amit Kumar",
    "ifsc_status": 1,
    "user_code": "35739001",
    "customer_id": "3287820071",
    "billDueDate": "20260728",
    "billdate": "null",
    "billDetailsList": [],
    "bbpstrxnrefid": "",
    "billername": ""
  },
  "response_type_id": 1052,
  "message": "Due Bill Amount For utility",
  "status": 0
}
```

## Error scenarios

| Status | response_type_id | Scenario |
| --- | --- | --- |
| 200 | `-1` | Required field missing |
| 200 | `1468` — Bill fetch failed. Verify the account details and retry after some time — do not proceed to payment. | Bill fetch failed at the biller |