API Test Keys

Create a Bill Request

POST

/v1/bill_payments/bill_requests

Click to copy

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.

Is this page helpful?

Curl

1curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
2-X POST https://api.razorpay.com/v1/bill_payments/bill_requests \
3-H "Content-Type: application/json" \
4-d '{
5  "biller_id": "biller_001",
6  "gateway_biller_id": "TPOW00000MUM01",
7  "customer": {
8    "id": "rzp_cust_123",
9    "name": "Gaurav Kumar",
10    "mobile": "919000090000",
11    "email": "gaurav.kumar@example.com"
12  },
13  "device": {
14    "initiating_channel": "MOB",
15    "mobile": "9999999999",
16    "geocode": "12.9667,77.5667",
17    "ip": "198.1.1.1",
18    "mac": "00-0D-60-07-2A-F0",
19    "os": "android",
20    "app": "amazon_pay"
21  },
22  "biller_data": {
23    "account_holder": {
24      "AccountNumber": "XXXXXXX",
25      "mobile": "XXXXXXX",
26      "AccountHolderName": "Gaurav Kumar",
27      "<KEY>": "<VALUE>"
28    }
29  }
30}'

Success (state=processing)

Failure (state=failed)

1{
2  "id": "billreq_ERNEungCtXpZqM",
3  "entity": "bill_payment.bill_request",
4  "status": "processing",
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  "gateway": "bbps",
14  "created_at": 1609459200
15}

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

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

Info about the bill payment initiating device.

device.initiating_channel

enum

The channel from which the bill request is initiated, based on NPCI terminology. Values:

INT - Web
MOB - Mobile App
MOBB - Mobile Banking App
INTB - Internet Banking
AGT - Agent
BNKBRNCH - Bank Branch
BSC - Business Correspondent

device.app

string

Application name (for example, amazon_pay). Required for MOB, MOBB initiating channels.

device.mobile

string

NPCI channel requirements - End agent's mobile number for offline channels like BNKBRNCH, AGT, BSC initiating channels.

device.geocode

string

NPCI channel requirements - Latitude, Longitude (for example, 12.9667,77.5667). Required for INT, MOB, BNKBRNCH, AGT, BSC channels.

device.ip

string

NPCI channel requirements - IP address (IPv4 or IPv6). Required for INT, INTB, MOB, MOBB initiating channels.

device.mac

string

MAC address. Required for INT, INTB channels.

device.os

string

Operating system. Required for MOB, MOBB channels. For example, android, iOS.

biller_data

object

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

biller_data.account_holder

object

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

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.

Error Status: 400

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

Solution

The gateway_biller_id is missing.

Error Status: 400

biller_id is required.

Solution

The biller_data.account_holder values are invalid.

Error Status: 400

Invalid customer parameter format for {param_name}.

Solution

Device information is incomplete.

Error Status: 400

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

Solution

No bill found for the provided customer parameters.

Error Status: 502

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

Solution

Unable to fetch bill from NPCI.

Error Status: 502

NPCI did not respond within the timeout window.

Solution

Invalid or missing customer account holder data.

Error Status: 502

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

Solution

Biller system temporarily unavailable.

Error Status: 502

The biller is temporarily unavailable to retrieve the bill.

Solution

Bill retrieval is not valid for this biller.

Error Status: 400

The biller does not support bill retrieval.

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

Create a Bill Request

POST

/v1/bill_payments/bill_requests

Click to copy

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.

Is this page helpful?

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

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

Info about the bill payment initiating device.

device.initiating_channel

enum

The channel from which the bill request is initiated, based on NPCI terminology. Values:

INT - Web
MOB - Mobile App
MOBB - Mobile Banking App
INTB - Internet Banking
AGT - Agent
BNKBRNCH - Bank Branch
BSC - Business Correspondent

device.app

string

Application name (for example, amazon_pay). Required for MOB, MOBB initiating channels.

device.mobile

string

NPCI channel requirements - End agent's mobile number for offline channels like BNKBRNCH, AGT, BSC initiating channels.

device.geocode

string

NPCI channel requirements - Latitude, Longitude (for example, 12.9667,77.5667). Required for INT, MOB, BNKBRNCH, AGT, BSC channels.

device.ip

string

NPCI channel requirements - IP address (IPv4 or IPv6). Required for INT, INTB, MOB, MOBB initiating channels.

device.mac

string

MAC address. Required for INT, INTB channels.

device.os

string

Operating system. Required for MOB, MOBB channels. For example, android, iOS.

biller_data

object

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

biller_data.account_holder

object

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

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.

Error Status: 400

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

Solution

The gateway_biller_id is missing.

Error Status: 400

biller_id is required.

Solution

The biller_data.account_holder values are invalid.

Error Status: 400

Invalid customer parameter format for {param_name}.

Solution

Device information is incomplete.

Error Status: 400

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

Solution

No bill found for the provided customer parameters.

Error Status: 502

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

Solution

Unable to fetch bill from NPCI.

Error Status: 502

NPCI did not respond within the timeout window.

Solution

Invalid or missing customer account holder data.

Error Status: 502

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

Solution

Biller system temporarily unavailable.

Error Status: 502

The biller is temporarily unavailable to retrieve the bill.

Solution

Bill retrieval is not valid for this biller.

Error Status: 400

The biller does not support bill retrieval.

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 POST https://api.razorpay.com/v1/bill_payments/bill_requests \
3-H "Content-Type: application/json" \
4-d '{
5  "biller_id": "biller_001",
6  "gateway_biller_id": "TPOW00000MUM01",
7  "customer": {
8    "id": "rzp_cust_123",
9    "name": "Gaurav Kumar",
10    "mobile": "919000090000",
11    "email": "gaurav.kumar@example.com"
12  },
13  "device": {
14    "initiating_channel": "MOB",
15    "mobile": "9999999999",
16    "geocode": "12.9667,77.5667",
17    "ip": "198.1.1.1",
18    "mac": "00-0D-60-07-2A-F0",
19    "os": "android",
20    "app": "amazon_pay"
21  },
22  "biller_data": {
23    "account_holder": {
24      "AccountNumber": "XXXXXXX",
25      "mobile": "XXXXXXX",
26      "AccountHolderName": "Gaurav Kumar",
27      "<KEY>": "<VALUE>"
28    }
29  }
30}'

Success (state=processing)

Failure (state=failed)

1{
2  "id": "billreq_ERNEungCtXpZqM",
3  "entity": "bill_payment.bill_request",
4  "status": "processing",
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  "gateway": "bbps",
14  "created_at": 1609459200
15}