API Test Keys

Fetch Bill Payment

GET

/v1/bill_payments/payments/:id

Click to copy

Retrieve the real-time status of a bill payment here. Since payments are processed asynchronously, poll this endpoint until the status reaches a terminal state of success or failed.

Polling Recommendation

Poll at intervals of 3–5 seconds. Most bill payments resolve within 30–60 seconds, but certain billers have extended processing windows. A pending status means NPCI has acknowledged the request but the biller has not confirmed. Continue polling.

Do Not Retry on Pending

Do not initiate a fresh Create a Bill Payment when the status is pending. The X-Bill-Payments-Idempotency header on the original request protects against duplicates only when the same key is replayed with an identical body. Poll this endpoint until the status reaches success or failed instead.

Payment State Machine

processing - Bill payment request created and sent to NPCI. Continue polling.
pending - NPCI has acknowledged the request but the biller has not confirmed. Continue polling. Do not retry.
success - NPCI confirmed the payment was accepted by the biller. Capture the PG payment if not already captured.
failed - Payment was rejected by NPCI or the biller. Initiate a refund on the PG payment if money was collected.

Is this page helpful?

Curl

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

status: success

status: pending

status: failed

Failure

1{
2  "id": "bill_pay_xxxx",
3  "entity": "bill_payment.payment",
4  "status": "success",
5  "gateway": "bbps",
6  "gateway_transaction_id": "bbps_txn_id",
7  "biller_id": "biller_001",
8  "gateway_biller_id": "TPOW00000MUM01",
9  "biller_transaction_id": "AB123456",
10  "direct_pay": false,
11  "bill_pay_amount": 1015,
12  "currency": "INR",
13  "fees": {
14    "app_convenience_fee": 10,
15    "biller_convenience_fee": 5
16  },
17  "customer": {
18    "id": "rzp_cust_123",
19    "name": "Gaurav Kumar",
20    "mobile": "919000090000",
21    "email": "gaurav.kumar@example.com"
22  },
23  "payment": [
24    {
25      "id": "pay_MbJ5AvwNpAkfLA",
26      "provider": "razorpay",
27      "amount": 600,
28      "currency": "INR",
29      "method": "card"
30    },
31    {
32      "id": "pay_MbJ5AvwNpAkfLB",
33      "provider": "razorpay",
34      "amount": 430,
35      "currency": "INR",
36      "method": "upi"
37    }
38  ],
39  "account_holder": {
40    "account_number": "XXXXXXX",
41    "KEY": "VALUE",
42    "KEY2": "VALUE2"
43  },
44  "bills": [
45    {
46      "bill_number": "820356722187",
47      "amount": 1015,
48      "currency": "INR",
49      "bill_date": 1609459200,
50      "due_date": 1609459200,
51      "bill_period": "monthly"
52    }
53  ],
54  "data": {
55    "mobile_number": "Text",
56    "KEY": "VALUE"
57  },
58  "error_code": null,
59  "error_description": null,
60  "error_source": null,
61  "error_step": null,
62  "error_reason": null
63}

Path Parameters

id

string

Unique identifier of the bill payment returned by

Create a Bill Payment

. For example, bill_pay_xxxx.

Response Parameters

id

string

Razorpay's unique bill payment transaction id.

entity

string

Indicates the type of entity. Always bill_payment.payment.

status

string

Current status of the bill payment. Possible values:

processing - Request created and sent to NPCI. Continue polling.
pending - NPCI acknowledged the request but the biller has not confirmed. Continue polling. Do not retry.
success - NPCI confirmed the payment was accepted by the biller.
failed - Payment was rejected by NPCI or the biller. See
error_*
fields for details.

gateway

string

Payment gateway. Always bbps.

gateway_transaction_id

string

BBPS/NPCI transaction reference id. Fixed length of 12 or 20 characters. Store this for reconciliation, settlement tracking and dispute resolution.

biller_id

string

Razorpay biller entity id.

gateway_biller_id

string

NPCI's biller id.

biller_transaction_id

string

Biller's internal transaction/receipt reference number. Present only when status is success. Share this with the customer as their BBPS payment reference.

direct_pay

boolean

true if the payment was made without a prior bill retrieval; false if a bill_request_id was provided. Derived by Razorpay. Not sent in the request.

bill_pay_amount

integer

Total bill amount paid in paise, excluding fees.

currency

string

Currency. Always INR.

fees

object

Fee breakdown.

fees.app_convenience_fee

integer

App/platform convenience fee charged to the customer, in paise.

fees.biller_convenience_fee

integer

Customer Convenience Fee (CCF) charged by the biller, in paise.

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's mobile number with country code. For example, 919000090000.

customer.email

string

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

payment

array

Array of payment method details collected via the Razorpay PG.

payment[].id

string

Razorpay payment entity id.

payment[].provider

string

Payment provider. Always razorpay.

payment[].amount

integer

Amount paid via the selected method, in paise.

payment[].currency

string

Payment currency. Always INR.

payment[].method

string

Payment method. Values: card, upi, netbanking, wallet.

account_holder

object

Bill account holder details 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

Array of bills paid in this transaction.

bills[].bill_number

string

Biller's bill reference/invoice number. Mandatory in multi-bill scenarios.

bills[].amount

integer

Individual bill amount in paise.

bills[].currency

string

Bill currency. Always INR.

bills[].bill_date

integer

Bill generation date as a UNIX timestamp.

bills[].due_date

integer

Bill payment due date as a UNIX timestamp.

bills[].bill_period

string

Billing frequency. Values: onetime, daily, monthly, quarterly, halfyearly, yearly.

data

object

Additional biller-specific metadata. Dynamic key-value pairs that vary by biller.

error_code

string

Error code. Present only when status is failed. Values: BAD_REQUEST_ERROR, GATEWAY_ERROR, SERVER_ERROR.

error_description

string

Human-readable error description.

error_source

string

Where the error originated. Values: customer, biller, gateway, razorpay.

error_step

string

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

error_reason

string

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

error_metadata

object

Additional context such as payment ids and gateway error codes.

created_at

integer

UNIX timestamp when the bill payment was created.

Errors

The bill payment id is invalid or not found.

Error Status: 400

No bill payment 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 Payment

GET

/v1/bill_payments/payments/:id

Click to copy

Retrieve the real-time status of a bill payment here. Since payments are processed asynchronously, poll this endpoint until the status reaches a terminal state of success or failed.

Polling Recommendation

Do Not Retry on Pending

Payment State Machine

processing - Bill payment request created and sent to NPCI. Continue polling.
pending - NPCI has acknowledged the request but the biller has not confirmed. Continue polling. Do not retry.
success - NPCI confirmed the payment was accepted by the biller. Capture the PG payment if not already captured.
failed - Payment was rejected by NPCI or the biller. Initiate a refund on the PG payment if money was collected.

Is this page helpful?

Path Parameters

id

string

Unique identifier of the bill payment returned by

Create a Bill Payment

. For example, bill_pay_xxxx.

Response Parameters

id

string

Razorpay's unique bill payment transaction id.

entity

string

Indicates the type of entity. Always bill_payment.payment.

status

string

Current status of the bill payment. Possible values:

processing - Request created and sent to NPCI. Continue polling.
pending - NPCI acknowledged the request but the biller has not confirmed. Continue polling. Do not retry.
success - NPCI confirmed the payment was accepted by the biller.
failed - Payment was rejected by NPCI or the biller. See
error_*
fields for details.

gateway

string

Payment gateway. Always bbps.

gateway_transaction_id

string

BBPS/NPCI transaction reference id. Fixed length of 12 or 20 characters. Store this for reconciliation, settlement tracking and dispute resolution.

biller_id

string

Razorpay biller entity id.

gateway_biller_id

string

NPCI's biller id.

biller_transaction_id

string

Biller's internal transaction/receipt reference number. Present only when status is success. Share this with the customer as their BBPS payment reference.

direct_pay

boolean

true if the payment was made without a prior bill retrieval; false if a bill_request_id was provided. Derived by Razorpay. Not sent in the request.

bill_pay_amount

integer

Total bill amount paid in paise, excluding fees.

currency

string

Currency. Always INR.

fees

object

Fee breakdown.

fees.app_convenience_fee

integer

App/platform convenience fee charged to the customer, in paise.

fees.biller_convenience_fee

integer

Customer Convenience Fee (CCF) charged by the biller, in paise.

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's mobile number with country code. For example, 919000090000.

customer.email

string

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

payment

array

Array of payment method details collected via the Razorpay PG.

payment[].id

string

Razorpay payment entity id.

payment[].provider

string

Payment provider. Always razorpay.

payment[].amount

integer

Amount paid via the selected method, in paise.

payment[].currency

string

Payment currency. Always INR.

payment[].method

string

Payment method. Values: card, upi, netbanking, wallet.

account_holder

object

bills

array

Array of bills paid in this transaction.

bills[].bill_number

string

Biller's bill reference/invoice number. Mandatory in multi-bill scenarios.

bills[].amount

integer

Individual bill amount in paise.

bills[].currency

string

Bill currency. Always INR.

bills[].bill_date

integer

Bill generation date as a UNIX timestamp.

bills[].due_date

integer

Bill payment due date as a UNIX timestamp.

bills[].bill_period

string

Billing frequency. Values: onetime, daily, monthly, quarterly, halfyearly, yearly.

data

object

Additional biller-specific metadata. Dynamic key-value pairs that vary by biller.

error_code

string

Error code. Present only when status is failed. Values: BAD_REQUEST_ERROR, GATEWAY_ERROR, SERVER_ERROR.

error_description

string

Human-readable error description.

error_source

string

Where the error originated. Values: customer, biller, gateway, razorpay.

error_step

string

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

error_reason

string

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

error_metadata

object

Additional context such as payment ids and gateway error codes.

created_at

integer

UNIX timestamp when the bill payment was created.

Errors

The bill payment id is invalid or not found.

Error Status: 400

No bill payment 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/payments/bill_pay_xxxx

status: success

status: pending

status: failed

Failure

1{
2  "id": "bill_pay_xxxx",
3  "entity": "bill_payment.payment",
4  "status": "success",
5  "gateway": "bbps",
6  "gateway_transaction_id": "bbps_txn_id",
7  "biller_id": "biller_001",
8  "gateway_biller_id": "TPOW00000MUM01",
9  "biller_transaction_id": "AB123456",
10  "direct_pay": false,
11  "bill_pay_amount": 1015,
12  "currency": "INR",
13  "fees": {
14    "app_convenience_fee": 10,
15    "biller_convenience_fee": 5
16  },
17  "customer": {
18    "id": "rzp_cust_123",
19    "name": "Gaurav Kumar",
20    "mobile": "919000090000",
21    "email": "gaurav.kumar@example.com"
22  },
23  "payment": [
24    {
25      "id": "pay_MbJ5AvwNpAkfLA",
26      "provider": "razorpay",
27      "amount": 600,
28      "currency": "INR",
29      "method": "card"
30    },
31    {
32      "id": "pay_MbJ5AvwNpAkfLB",
33      "provider": "razorpay",
34      "amount": 430,
35      "currency": "INR",
36      "method": "upi"
37    }
38  ],
39  "account_holder": {
40    "account_number": "XXXXXXX",
41    "KEY": "VALUE",
42    "KEY2": "VALUE2"
43  },
44  "bills": [
45    {
46      "bill_number": "820356722187",
47      "amount": 1015,
48      "currency": "INR",
49      "bill_date": 1609459200,
50      "due_date": 1609459200,
51      "bill_period": "monthly"
52    }
53  ],
54  "data": {
55    "mobile_number": "Text",
56    "KEY": "VALUE"
57  },
58  "error_code": null,
59  "error_description": null,
60  "error_source": null,
61  "error_step": null,
62  "error_reason": null
63}