Bill Fetch

Query and retrieve the current outstanding bill details (such as customer name, bill amount, and due date) for a utility account before making a payment.

Endpoint: /v1/bbps/bill-fetch
Method: POST
Content-Type: application/json
Authentication: Required (Basic Auth)

Request Body Parameters

Field	Type	Required	Description
`operator_id`	string \| integer	Yes	The unique identifier of the operator (e.g. `101`).
`p_order_id`	string	Yes	A unique query ID generated by your application to prevent duplicate requests.
`params`	object	Yes	A key-value map containing the query parameters required by the specific operator.

Request Body Example

{
    "operator_id": "101",
    "params": [
        {
            "param_name": "number",
            "value": "ABC1023010"
        }
    ],
    "p_order_id": "PA23457865654"
}

Success Response (200 OK)

{
    "success": true,
    "bill": {
        "bill_amount": "66153.57",
        "bill_net_amount": "66153.57",
        "bill_date": "03 Jul 2026",
        "due_date": "2026-07-21",
        "min_bill_amount": "",
        "accept_payment": true,
        "accept_part_pay": "",
        "customer_name": "",
        "customer_ref_id": "12435676887"
    },
    "orderId": "BE5678904657890",
    "partnerOrderId": "R917454657897689"
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the bill fetch request succeeded.
`bill`	object \| null	The outstanding bill details if found. Contains `amount`, `customer_name`, `due_date`, `bill_date`, and `bill_number`.
`bill.amount`	float	The unpaid bill amount in INR.
`bill.customer_name`	string	The name of the customer registered with the utility operator.
`bill.due_date`	string	The due date for the bill payment (YYYY-MM-DD).
`bill.bill_date`	string	The bill generation date (YYYY-MM-DD).
`bill.bill_number`	string	The invoice/bill number.
`orderId`	string \| null	The upstream provider’s unique ID for this fetch transaction.
`partnerOrderId`	string \| null	The `p_order_id` you supplied in the request.

Error Responses

Invalid Parameters (400 Bad Request)

{
  "error": "Invalid request parameters"
}

Unknown Operator (400 Bad Request)

{
  "error": "Biller not found or inactive"
}

Provider Fetch Error (400 Bad Request)

Returned when the upstream provider fails to locate the bill (e.g. invalid customer account number).

{
  "success": false,
  "message": "Invalid customer account number or bill not generated yet."
}

Getting Started

Balance API

Recharge API

BBPS API

Request Body Parameters

Request Body Example

Success Response (200 OK)

Response Fields

Error Responses

Invalid Parameters (400 Bad Request)

Unknown Operator (400 Bad Request)

Provider Fetch Error (400 Bad Request)

​Request Body Parameters

​Request Body Example

​Success Response (200 OK)

​Response Fields

​Error Responses

​Invalid Parameters (400 Bad Request)

​Unknown Operator (400 Bad Request)

​Provider Fetch Error (400 Bad Request)

Request Body Parameters

Request Body Example

Success Response (200 OK)

Response Fields

Error Responses

Invalid Parameters (400 Bad Request)

Unknown Operator (400 Bad Request)

Provider Fetch Error (400 Bad Request)