curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/bill_payments/bill_requests/billreq_ERNEungCtXpZqM
{
"id": "billreq_ERNEungCtXpZqM",
"entity": "bill_payment.bill_request",
"status": "success",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"gateway": "bbps",
"created_at": 1609459200,
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"account_holder_name": "Gaurav Kumar",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly",
"amount_details": {
"min_amount_due": 500,
"current_outstanding_amount": 1015,
"<KEY>": "<VALUE>"
}
}
],
"data": {
"email": "gaurav.kumar@example.com",
"KEY2": "VALUE2",
"KEY3": "VALUE3"
}
}
{
"id": "billreq_ERNEungCtXpZqM",
"entity": "bill_payment.bill_request",
"status": "failed",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"created_at": 1609459200,
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [],
"data": {
"email": "gaurav.kumar@example.com",
"KEY2": "VALUE2",
"KEY3": "VALUE3"
},
"error_code": "BAD_REQUEST_ERROR",
"error_description": "No bill is currently available for this customer account. The customer may have no outstanding dues or the bill for this cycle has not yet been generated.",
"error_source": "biller",
"error_step": "bill_request",
"error_reason": "no_outstanding_bill"
}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The bill request id is invalid.",
"source": "business",
"step": "validation",
"reason": "invalid_bill_request_id"
}
}
Fetch Bill Request | BBPS API | Razorpay
Poll the status and details of a BBPS bill request using Razorpay’s Bill Payments API. Returns processing, success or failed status with bill amount and due date on success.
GET
/
v1
/
bill_payments
/
bill_requests
/
:id
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/bill_payments/bill_requests/billreq_ERNEungCtXpZqM
{
"id": "billreq_ERNEungCtXpZqM",
"entity": "bill_payment.bill_request",
"status": "success",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"gateway": "bbps",
"created_at": 1609459200,
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"account_holder_name": "Gaurav Kumar",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly",
"amount_details": {
"min_amount_due": 500,
"current_outstanding_amount": 1015,
"<KEY>": "<VALUE>"
}
}
],
"data": {
"email": "gaurav.kumar@example.com",
"KEY2": "VALUE2",
"KEY3": "VALUE3"
}
}
{
"id": "billreq_ERNEungCtXpZqM",
"entity": "bill_payment.bill_request",
"status": "failed",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"created_at": 1609459200,
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [],
"data": {
"email": "gaurav.kumar@example.com",
"KEY2": "VALUE2",
"KEY3": "VALUE3"
},
"error_code": "BAD_REQUEST_ERROR",
"error_description": "No bill is currently available for this customer account. The customer may have no outstanding dues or the bill for this cycle has not yet been generated.",
"error_source": "biller",
"error_step": "bill_request",
"error_reason": "no_outstanding_bill"
}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The bill request id is invalid.",
"source": "business",
"step": "validation",
"reason": "invalid_bill_request_id"
}
}
Available in🇮🇳 India
Use this endpoint to retrieve the status and details of a bill request created via the Create a Bill Request API. Since bill requests are processed asynchronously, poll this endpoint until the status reaches a terminal state of success or failed. On success, the response contains the bill details, account holder information and any biller-specific metadata required for the next step.
Polling RecommendationPoll at intervals of 2-5 seconds. The bill retrieval typically completes within 10-30 seconds depending on the biller’s response time.
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/bill_payments/bill_requests/billreq_ERNEungCtXpZqM
{
"id": "billreq_ERNEungCtXpZqM",
"entity": "bill_payment.bill_request",
"status": "success",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"gateway": "bbps",
"created_at": 1609459200,
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"account_holder_name": "Gaurav Kumar",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly",
"amount_details": {
"min_amount_due": 500,
"current_outstanding_amount": 1015,
"<KEY>": "<VALUE>"
}
}
],
"data": {
"email": "gaurav.kumar@example.com",
"KEY2": "VALUE2",
"KEY3": "VALUE3"
}
}
{
"id": "billreq_ERNEungCtXpZqM",
"entity": "bill_payment.bill_request",
"status": "failed",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"created_at": 1609459200,
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [],
"data": {
"email": "gaurav.kumar@example.com",
"KEY2": "VALUE2",
"KEY3": "VALUE3"
},
"error_code": "BAD_REQUEST_ERROR",
"error_description": "No bill is currently available for this customer account. The customer may have no outstanding dues or the bill for this cycle has not yet been generated.",
"error_source": "biller",
"error_step": "bill_request",
"error_reason": "no_outstanding_bill"
}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The bill request id is invalid.",
"source": "business",
"step": "validation",
"reason": "invalid_bill_request_id"
}
}
Path Parameters
Response Parameters
Request status. Possible values:
processing- The request is in progress. Continue polling.success- Bill details retrieved successfully. Proceed to create a payment.failed- Bill retrieval failed, including when the biller (NPCI) responds that no bill is available. Seeerror_*fields for details.
Customer reference details echoed from the request as dynamic key-value pairs. Returned only when sent in the request. Free-form metadata that you can use for your own tracking and reconciliation.
Dynamic key-value pair holding your customer reference. Echoed back exactly as sent in the request. Not validated by Razorpay.
Dynamic key-value pair holding the customer name. Echoed back exactly as sent in the request. Not validated by Razorpay.
Dynamic key-value pair holding the customer email. Echoed back exactly as sent in the request. Not validated by Razorpay.
Details of the bill account holder, i.e. the actual user whose bill is being paid. Returned as dynamic key-value pairs defined by the biller’s
account_holder_config (NPCI biller MDM). The keys and values vary by biller. Razorpay does not control either.Billing frequency. Values:
onetime, daily, weekly, monthly, bimonthly, quarterly, halfyearly, yearly. Show the billing frequency of the bill on UI/UX.Amount breakup returned as dynamic key-value pairs defined by the biller (NPCI biller MDM). The keys and values vary by biller category. Razorpay does not control either. Show as part of amount breakup in UI/UX.
Dynamic key-value pair holding the minimum amount due in paise. Returned only when sent by the biller. Varies by biller category.
Dynamic key-value pair holding the current outstanding amount in paise. Returned only when sent by the biller. Varies by biller category.
Dynamic key-value pairs of information sent by biller. Razorpay does not control this. Show biller-specific customer data on receipt. For FASTag billers, one of the key-value pairs is
Wallet Balance, which the merchant can use to check the current FASTag balance of the merchant.Last modified on October 8, 2026
Was this page helpful?