Create a Bill Request | BBPS API | Razorpay

Initiate an asynchronous request to retrieve a customer’s outstanding bill from a BBPS biller using Razorpay’s Bill Payments API. Poll Fetch Bill Request for results.

POST /v1/bill_payments/bill_requests

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/bill_payments/bill_requests \
-H "Content-Type: application/json" \
-d '{
  "biller_id": "biller_001",
  "gateway_biller_id": "TPOW00000MUM01",
  "customer": {
    "id": "rzp_cust_123",
    "name": "Gaurav Kumar",
    "mobile": "919000090000",
    "email": "[e-mail]"
  },
  "device": {
    "initiating_channel": "mobile",
    "mobile": "9999999999",
    "geocode": "12.9667,77.5667",
    "ip": "198.1.1.1",
    "mac": "00-0D-60-07-2A-F0",
    "os": "android",
    "imei": "490154203237518",
    "app": "amazon_pay"
  },
  "biller_data": {
    "account_holder": {
      "account_number": "XXXXXXX",
      "KEY": "VALUE",
      "KEY2": "VALUE2"
    }
  }
}'

Success (state=processing)

{
  "id": "billreq_ERNEungCtXpZqM",
  "entity": "bill_payment.bill_request",
  "status": "processing",
  "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
}

Available in🇮🇳 India

Use this endpoint to either retrieve the outstanding bill amount for a customer from a biller or validate the customer’s account details when the biller does not support bill retrieval. This is an asynchronous API. The response immediately returns a bill request in processing status. Poll the Fetch Bill Request API with the returned id until the status reaches success or failed.

When to use this API

• When the biller’s bill_request_config.bill_request_required is mandatory - call this API to retrieve the bill before payment.
• When bill_request_required is optional - call this API to validate the customer’s account or skip and use Direct Pay.
• When bill_request_required is not_supported - skip this step and call Create a Bill Payment directly.

Polling URL

Poll for the final state using GET /v1/bill_payments/bill_requests/{id} with the id from the response.

Curl

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/bill_payments/bill_requests \
-H "Content-Type: application/json" \
-d '{
  "biller_id": "biller_001",
  "gateway_biller_id": "TPOW00000MUM01",
  "customer": {
    "id": "rzp_cust_123",
    "name": "Gaurav Kumar",
    "mobile": "919000090000",
    "email": "[e-mail]"
  },
  "device": {
    "initiating_channel": "mobile",
    "mobile": "9999999999",
    "geocode": "12.9667,77.5667",
    "ip": "198.1.1.1",
    "mac": "00-0D-60-07-2A-F0",
    "os": "android",
    "imei": "490154203237518",
    "app": "amazon_pay"
  },
  "biller_data": {
    "account_holder": {
      "account_number": "XXXXXXX",
      "KEY": "VALUE",
      "KEY2": "VALUE2"
    }
  }
}'

Success (state=processing)

{
  "id": "billreq_ERNEungCtXpZqM",
  "entity": "bill_payment.bill_request",
  "status": "processing",
  "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
}

Request Parameters

biller_id · string

Razorpay’s internal biller id sent in biller info. One of biller_id or gateway_biller_id is mandatory.

gateway_biller_id · string

NPCI biller id (for example, TPOW00000MUM01). One of biller_id or gateway_biller_id is mandatory.

customer · object

Customer information passed as dynamic key-value pairs. Free-form metadata for your own tracking and reconciliation. Razorpay echoes these back on responses and webhooks without validation.

customer.id · string

Dynamic key-value pair holding your customer reference. Not validated by Razorpay.

customer.name · string

Dynamic key-value pair holding the customer name. 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. Not validated by Razorpay.

device · object · required

Info about the bill payment initiating device.

device.initiating_channel · enum · required

Channel from which the bill request is initiated. Values:

• internet - Web
• mobile - Mobile App
• pos - Point of Sale
• mpos - Mobile Point of Sale

device.app · string

Application name (for example, amazon_pay). Required for mobile, mpos initiating channels.

device.mobile · string

NPCI channel requirements - End agent’s mobile number for offline channels. Required for pos, mpos initiating channels.

device.geocode · string

NPCI channel requirements - Latitude, Longitude (for example, 12.9667,77.5667). Required for internet, mobile, pos, mpos channels.

device.ip · string

NPCI channel requirements - IP address (IPv4 or IPv6). Required for internet, mobile initiating channels.

device.mac · string

MAC address. Required for internet channels.

device.os · string

Operating system. Required for mobile, mpos channels. For example, android, iOS.

device.imei · string

Device IMEI number. Required for the mobile initiating channel.

biller_data · object · required

Bill account holder details. Required for every bill request irrespective of the pay flow.

biller_data.account_holder · object · required

Dynamic key-value pairs that identify the customer’s account at the biller. Razorpay does not control the keys nor the values. Pass them exactly as defined in the biller’s account_holder_config returned by the Fetch Billers API.

Response Parameters

id · string

Razorpay’s bill request id created. Store for reference and reconciliation. For example, billreq_ERNEungCtXpZqM.

entity · string

Entity type. Always bill_payment.bill_request.

status · string

Request status. Possible values: processing, success, failed. To take next action if the status is not terminal (success or failed), continue polling.

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 sent in request. 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.

Errors

The `biller_id` is missing or invalid.

Code: 400

The biller id provided does not correspond to a valid or active biller.

Solution: Verify the biller_id and retry with a valid biller from the Fetch Billers API.

The `gateway_biller_id` is missing.

Code: 400

biller_id is required.

Solution: Pass either a valid biller_id or gateway_biller_id in the request.

The `biller_data.account_holder` values are invalid.

Code: 400

Invalid customer parameter format for {param_name}.

Solution: Pass values matching the biller’s account_holder_config.params validation rules (data_type, min_length, max_length, regex).

Device information is incomplete.

Code: 400

Device information is incomplete. Missing required field for the initiating channel.

Solution: Pass all device fields required for the chosen initiating_channel.

No bill found for the provided customer parameters.

Code: 502

No bill found at the biller for the customer details provided.

Solution: Confirm the customer details with the user and retry.

Unable to fetch bill from NPCI.

Code: 502

NPCI did not respond within the timeout window.

Solution: Retry the request after a short interval.

Invalid or missing customer account holder data.

Code: 502

The biller rejected the account holder data as invalid or incomplete.

Solution: Verify biller_data.account_holder keys match the biller’s account_holder_config.

Biller system temporarily unavailable.

Code: 502

The biller is temporarily unavailable to retrieve the bill.

Solution: Retry the request after a short interval.

Bill retrieval is not valid for this biller.

Code: 400

The biller does not support bill retrieval.

Solution: Use Direct Pay via the Create a Bill Payment API. Check the biller’s bill_request_config.bill_request_required before calling this 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.