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

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

Success (bills exist)

{
  "id": "billreq_ERNEungCtXpZqM",
  "entity": "bill_payment.bill_request",
  "status": "success",
  "customer": {
    "id": "rzp_cust_123",
    "name": "Gaurav Kumar",
    "mobile": "919000090000",
    "email": "[e-mail]"
  },
  "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": "[e-mail]",
    "KEY2": "VALUE2",
    "KEY3": "VALUE3"
  }
}

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 Recommendation

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

Curl

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

Success (bills exist)

{
  "id": "billreq_ERNEungCtXpZqM",
  "entity": "bill_payment.bill_request",
  "status": "success",
  "customer": {
    "id": "rzp_cust_123",
    "name": "Gaurav Kumar",
    "mobile": "919000090000",
    "email": "[e-mail]"
  },
  "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": "[e-mail]",
    "KEY2": "VALUE2",
    "KEY3": "VALUE3"
  }
}

Path Parameters

id · string · required

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 · required

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.

Code: 400

No bill request was found for the provided id.

Solution: Verify the id matches the one returned by the Create a Bill Request API.

The API `<key/secret> ` provided is invalid.

Code: 401

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

Solution: Ensure your API key and secret are correct and active.