API Test Keys

Fetch Bill Request

GET

/v1/bill_payments/bill_requests/:id

Click to copy

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 Recommendation

Poll at intervals of 2-5 seconds. The bill retrieval typically completes within 10-30 seconds depending on the biller's response time.

Is this page helpful?

Curl

1curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2-X GET https://api.razorpay.com/v1/bill_payments/bill_requests/billreq_ERNEungCtXpZqM

Success (bills do not exist)

Success (bills exist)

Failure

1{
2  "id": "billreq_ERNEungCtXpZqM",
3  "entity": "bill_payment.bill_request",
4  "status": "success",
5  "customer": {
6    "id": "rzp_cust_123",
7    "name": "Gaurav Kumar",
8    "mobile": "919000090000",
9    "email": "gaurav.kumar@example.com"
10  },
11  "biller_id": "biller_001",
12  "gateway_biller_id": "TPOW00000MUM01",
13  "created_at": 1609459200,
14  "account_holder": {
15    "AccountHolderName": "Gaurav Kumar",
16    "<KEY>": "<VALUE>"
17  },
18  "bills": [],
19  "data": {
20    "email": "gaurav.kumar@example.com",
21    "KEY2": "VALUE2",
22    "KEY3": "VALUE3"
23  },
24  "error_code": "BAD_REQUEST_ERROR",
25  "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.",
26  "error_source": "biller",
27  "error_step": "bill_request",
28  "error_reason": "no_outstanding_bill"
29}

Path Parameters

id

string

Razorpay's bill request id created. For example, billreq_ERNEungCtXpZqM.

Response Parameters

id

string

Razorpay's bill request id. Store for reference and reconciliation.

entity

string

Entity type. Always bill_payment.bill_request.

status

string

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. See
error_*
fields for details.

customer

object

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.

customer.id

string

Dynamic key-value pair holding your customer reference. Echoed back exactly as sent in the request. Not validated by Razorpay.

customer.name

string

Dynamic key-value pair holding the customer name. Echoed back exactly as sent in the request. Not validated by Razorpay.

customer.mobile

string

Customer mobile number provided at payment create on PA.

customer.email

string

Dynamic key-value pair holding the customer email. Echoed back exactly as sent in the request. Not validated by Razorpay.

biller_id

string

Razorpay's internal biller id, same as sent in request. Use for reference and reconciliation.

gateway_biller_id

string

NPCI biller id. Use for reference and reconciliation.

gateway

string

Bill payment gateway used. Default value is bbps.

created_at

integer

Request created timestamp at Razorpay (Unix seconds). Audit trail.

account_holder

object

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.

bills

array

Bill details if a bill is retrieved against the request. Empty array if not available.

bills[].bill_number

string

Bill number given from biller. Show bill reference number on UI/UX.

bills[].amount

integer

Total bill amount provided by biller in paise. Show the bill amount to be paid by customer.

bills[].currency

string

Default to INR. Show the currency of the amount in their UI/UX.

bills[].account_holder_name

string

Account holder name as per the biller record. Verify against account_holder data.

bills[].bill_date

integer

Bill generation date from biller (Unix seconds). Show the bill generated date on UI/UX.

bills[].due_date

integer

Bill due date from biller (Unix seconds). Show the due date of the bill on UI/UX.

bills[].bill_period

enum

Billing frequency. Values: onetime, daily, weekly, monthly, bimonthly, quarterly, halfyearly, yearly. Show the billing frequency of the bill on UI/UX.

bills[].amount_details

object

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.

bills[].amount_details.min_amount_due

integer

Dynamic key-value pair holding the minimum amount due in paise. Returned only when sent by the biller. Varies by biller category.

bills[].amount_details.current_outstanding_amount

integer

Dynamic key-value pair holding the current outstanding amount in paise. Returned only when sent by the biller. Varies by biller category.

data

object

Dynamic key-value pairs of information sent by biller. Razorpay does not control this. Show biller-specific customer data on receipt.

error_code

string

Error code if status is failed or if no bill is available. For example, BAD_REQUEST_ERROR, GATEWAY_ERROR.

error_description

string

Human-readable error description.

error_source

string

Origin of the error. Values: customer, biller, gateway, business.

error_step

string

Step at which the error occurred. For example, bill_request, validation.

error_reason

string

Programmatic error reason code. Use for error-specific handling logic.

Errors

The bill request id is invalid or not found.

Error Status: 400

No bill request was found for the provided id.

Solution

The API <key/secret> provided is invalid.

Error Status: 401

The API credentials passed in the request differ from the ones generated on the Dashboard.

Solution

Fetch Bill Request

GET

/v1/bill_payments/bill_requests/:id

Click to copy

Use this endpoint to retrieve the status and details of a bill request created via the

Create a Bill Request

Polling Recommendation

Poll at intervals of 2-5 seconds. The bill retrieval typically completes within 10-30 seconds depending on the biller's response time.

Is this page helpful?

Path Parameters

id

string

Razorpay's bill request id created. For example, billreq_ERNEungCtXpZqM.

Response Parameters

id

string

Razorpay's bill request id. Store for reference and reconciliation.

entity

string

Entity type. Always bill_payment.bill_request.

status

string

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. See
error_*
fields for details.

customer

object

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.

customer.id

string

Dynamic key-value pair holding your customer reference. Echoed back exactly as sent in the request. Not validated by Razorpay.

customer.name

string

Dynamic key-value pair holding the customer name. Echoed back exactly as sent in the request. Not validated by Razorpay.

customer.mobile

string

Customer mobile number provided at payment create on PA.

customer.email

string

Dynamic key-value pair holding the customer email. Echoed back exactly as sent in the request. Not validated by Razorpay.

biller_id

string

Razorpay's internal biller id, same as sent in request. Use for reference and reconciliation.

gateway_biller_id

string

NPCI biller id. Use for reference and reconciliation.

gateway

string

Bill payment gateway used. Default value is bbps.

created_at

integer

Request created timestamp at Razorpay (Unix seconds). Audit trail.

account_holder

object

bills

array

Bill details if a bill is retrieved against the request. Empty array if not available.

bills[].bill_number

string

Bill number given from biller. Show bill reference number on UI/UX.

bills[].amount

integer

Total bill amount provided by biller in paise. Show the bill amount to be paid by customer.

bills[].currency

string

Default to INR. Show the currency of the amount in their UI/UX.

bills[].account_holder_name

string

Account holder name as per the biller record. Verify against account_holder data.

bills[].bill_date

integer

Bill generation date from biller (Unix seconds). Show the bill generated date on UI/UX.

bills[].due_date

integer

Bill due date from biller (Unix seconds). Show the due date of the bill on UI/UX.

bills[].bill_period

enum

Billing frequency. Values: onetime, daily, weekly, monthly, bimonthly, quarterly, halfyearly, yearly. Show the billing frequency of the bill on UI/UX.

bills[].amount_details

object

bills[].amount_details.min_amount_due

integer

Dynamic key-value pair holding the minimum amount due in paise. Returned only when sent by the biller. Varies by biller category.

bills[].amount_details.current_outstanding_amount

integer

Dynamic key-value pair holding the current outstanding amount in paise. Returned only when sent by the biller. Varies by biller category.

data

object

Dynamic key-value pairs of information sent by biller. Razorpay does not control this. Show biller-specific customer data on receipt.

error_code

string

Error code if status is failed or if no bill is available. For example, BAD_REQUEST_ERROR, GATEWAY_ERROR.

error_description

string

Human-readable error description.

error_source

string

Origin of the error. Values: customer, biller, gateway, business.

error_step

string

Step at which the error occurred. For example, bill_request, validation.

error_reason

string

Programmatic error reason code. Use for error-specific handling logic.

Errors

The bill request id is invalid or not found.

Error Status: 400

No bill request was found for the provided id.

Solution

The API <key/secret> provided is invalid.

Error Status: 401

The API credentials passed in the request differ from the ones generated on the Dashboard.

Solution

Curl

1curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2-X GET https://api.razorpay.com/v1/bill_payments/bill_requests/billreq_ERNEungCtXpZqM

Success (bills do not exist)

Success (bills exist)

Failure

1{
2  "id": "billreq_ERNEungCtXpZqM",
3  "entity": "bill_payment.bill_request",
4  "status": "success",
5  "customer": {
6    "id": "rzp_cust_123",
7    "name": "Gaurav Kumar",
8    "mobile": "919000090000",
9    "email": "gaurav.kumar@example.com"
10  },
11  "biller_id": "biller_001",
12  "gateway_biller_id": "TPOW00000MUM01",
13  "created_at": 1609459200,
14  "account_holder": {
15    "AccountHolderName": "Gaurav Kumar",
16    "<KEY>": "<VALUE>"
17  },
18  "bills": [],
19  "data": {
20    "email": "gaurav.kumar@example.com",
21    "KEY2": "VALUE2",
22    "KEY3": "VALUE3"
23  },
24  "error_code": "BAD_REQUEST_ERROR",
25  "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.",
26  "error_source": "biller",
27  "error_step": "bill_request",
28  "error_reason": "no_outstanding_bill"
29}