Create a Bill Request | BBPS API | Razorpay

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": "gaurav.kumar@example.com"
  },
  "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"
    }
  }
}'

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

{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The biller id provided does not correspond to a valid or active biller. Verify the biller_id and retry with a valid biller.",
    "source": "business",
    "step": "bill_request",
    "reason": "biller_not_found"
  }
}

POST

bill_payments

bill_requests

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": "gaurav.kumar@example.com"
  },
  "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"
    }
  }
}'

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

{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The biller id provided does not correspond to a valid or active biller. Verify the biller_id and retry with a valid biller.",
    "source": "business",
    "step": "bill_request",
    "reason": "biller_not_found"
  }
}

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 URLPoll for the final state using GET /v1/bill_payments/bill_requests/{id} with the id from the response.

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": "gaurav.kumar@example.com"
  },
  "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"
    }
  }
}'

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

{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The biller id provided does not correspond to a valid or active biller. Verify the biller_id and retry with a valid biller.",
    "source": "business",
    "step": "bill_request",
    "reason": "biller_not_found"
  }
}

Request Parameters

string

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

string

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

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.

string

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

string

Dynamic key-value pair holding the customer name. Not validated by Razorpay.

string

required

Customer mobile number provided at payment create on PA.

string

Dynamic key-value pair holding the customer email. Not validated by Razorpay.

object

required

Info about the bill payment initiating device.

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

string

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

string

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

string

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

string

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

string

MAC address. Required for internet channels.

string

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

string

Device IMEI number. Required for the mobile initiating channel.

object

required

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

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

string

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

string

Entity type. Always bill_payment.bill_request.

string

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

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.

string

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

string

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

string

required

Customer mobile number provided at payment create on PA.

string

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

string

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

string

NPCI biller id sent in request. Use for reference and reconciliation.

string

Bill payment gateway used. Default value is bbps.

integer

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

Errors

The biller_id is missing or invalid.

Code: 400The 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: 400biller_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: 400Invalid 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: 400Device 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: 502No 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: 502NPCI did not respond within the timeout window.Solution: Retry the request after a short interval.

Invalid or missing customer account holder data.

Code: 502The 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: 502The 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: 400The 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: 401The 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.

Last modified on October 8, 2026

​Request Parameters

​Response Parameters

​Errors

Request Parameters

Response Parameters

Errors