curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/bill_payments/payments/bill_pay_xxxx
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "success",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"biller_transaction_id": "AB123456",
"direct_pay": false,
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"payment": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"provider": "razorpay",
"amount": 600,
"currency": "INR",
"method": "card"
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"provider": "razorpay",
"amount": 430,
"currency": "INR",
"method": "upi"
}
],
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly"
}
],
"data": {
"mobile_number": "Text",
"KEY": "VALUE"
},
"error_code": null,
"error_description": null,
"error_source": null,
"error_step": null,
"error_reason": null
}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "pending",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"created_at": 1609459200
}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "failed",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"biller_transaction_id": null,
"direct_pay": false,
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"payment": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"provider": "razorpay",
"amount": 600,
"currency": "INR",
"method": "card"
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"provider": "razorpay",
"amount": 430,
"currency": "INR",
"method": "upi"
}
],
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly"
}
],
"data": {
"mobile_number": "Text",
"KEY": "VALUE"
},
"error_code": "BAD_REQUEST_ERROR",
"error_description": "The payment method used is not supported by this biller. Check the biller's supported payment methods and retry with a supported method.",
"error_source": "biller",
"error_step": "bill_payment",
"error_reason": "biller_unavailable"
}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The bill payment id is invalid",
"source": "NA",
"step": "NA",
"reason": "NA",
"metadata": {}
}
}
Fetch Bill Payment | BBPS API | Razorpay
Poll the status and details of a BBPS bill payment using Razorpay’s Bill Payments API. Returns processing, pending, success or failed status along with transaction reference and bill details.
GET
/
v1
/
bill_payments
/
payments
/
:id
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/bill_payments/payments/bill_pay_xxxx
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "success",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"biller_transaction_id": "AB123456",
"direct_pay": false,
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"payment": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"provider": "razorpay",
"amount": 600,
"currency": "INR",
"method": "card"
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"provider": "razorpay",
"amount": 430,
"currency": "INR",
"method": "upi"
}
],
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly"
}
],
"data": {
"mobile_number": "Text",
"KEY": "VALUE"
},
"error_code": null,
"error_description": null,
"error_source": null,
"error_step": null,
"error_reason": null
}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "pending",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"created_at": 1609459200
}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "failed",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"biller_transaction_id": null,
"direct_pay": false,
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"payment": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"provider": "razorpay",
"amount": 600,
"currency": "INR",
"method": "card"
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"provider": "razorpay",
"amount": 430,
"currency": "INR",
"method": "upi"
}
],
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly"
}
],
"data": {
"mobile_number": "Text",
"KEY": "VALUE"
},
"error_code": "BAD_REQUEST_ERROR",
"error_description": "The payment method used is not supported by this biller. Check the biller's supported payment methods and retry with a supported method.",
"error_source": "biller",
"error_step": "bill_payment",
"error_reason": "biller_unavailable"
}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The bill payment id is invalid",
"source": "NA",
"step": "NA",
"reason": "NA",
"metadata": {}
}
}
Available in🇮🇳 India
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 RecommendationPoll 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 PendingDo 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.
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X GET https://api.razorpay.com/v1/bill_payments/payments/bill_pay_xxxx
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "success",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"biller_transaction_id": "AB123456",
"direct_pay": false,
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"payment": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"provider": "razorpay",
"amount": 600,
"currency": "INR",
"method": "card"
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"provider": "razorpay",
"amount": 430,
"currency": "INR",
"method": "upi"
}
],
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly"
}
],
"data": {
"mobile_number": "Text",
"KEY": "VALUE"
},
"error_code": null,
"error_description": null,
"error_source": null,
"error_step": null,
"error_reason": null
}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "pending",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"created_at": 1609459200
}
{
"id": "bill_pay_xxxx",
"entity": "bill_payment.payment",
"status": "failed",
"gateway": "bbps",
"gateway_transaction_id": "bbps_txn_id",
"biller_id": "biller_001",
"gateway_biller_id": "TPOW00000MUM01",
"biller_transaction_id": null,
"direct_pay": false,
"bill_pay_amount": 1015,
"currency": "INR",
"fees": {
"app_convenience_fee": 10,
"biller_convenience_fee": 5
},
"customer": {
"id": "rzp_cust_123",
"name": "Gaurav Kumar",
"mobile": "919000090000",
"email": "gaurav.kumar@example.com"
},
"payment": [
{
"id": "pay_MbJ5AvwNpAkfLA",
"provider": "razorpay",
"amount": 600,
"currency": "INR",
"method": "card"
},
{
"id": "pay_MbJ5AvwNpAkfLB",
"provider": "razorpay",
"amount": 430,
"currency": "INR",
"method": "upi"
}
],
"account_holder": {
"account_number": "XXXXXXX",
"KEY": "VALUE",
"KEY2": "VALUE2"
},
"bills": [
{
"bill_number": "820356722187",
"amount": 1015,
"currency": "INR",
"bill_date": 1609459200,
"due_date": 1609459200,
"bill_period": "monthly"
}
],
"data": {
"mobile_number": "Text",
"KEY": "VALUE"
},
"error_code": "BAD_REQUEST_ERROR",
"error_description": "The payment method used is not supported by this biller. Check the biller's supported payment methods and retry with a supported method.",
"error_source": "biller",
"error_step": "bill_payment",
"error_reason": "biller_unavailable"
}
{
"error": {
"code": "BAD_REQUEST_ERROR",
"description": "The bill payment id is invalid",
"source": "NA",
"step": "NA",
"reason": "NA",
"metadata": {}
}
}
Path Parameters
string
required
Unique identifier of the bill payment returned by Create a Bill Payment. For example,
bill_pay_xxxx.Response Parameters
string
Razorpay’s unique bill payment transaction id.
string
Indicates the type of entity. Always
bill_payment.payment.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. Seeerror_*fields for details.
string
Payment gateway. Always
bbps.string
BBPS/NPCI transaction reference id. Fixed length of 12 or 20 characters. Store this for reconciliation, settlement tracking and dispute resolution.
string
Razorpay biller entity id.
string
NPCI’s biller 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.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.integer
Total bill amount paid in paise, excluding fees.
string
Currency. Always
INR.object
Fee breakdown.
integer
App/platform convenience fee charged to the customer, in paise.
integer
Customer Convenience Fee (CCF) charged by the biller, in paise.
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’s mobile number with country code. For example,
919000090000.string
Dynamic key-value pair holding the customer email. Echoed back exactly as sent in the request. Not validated by Razorpay.
array
Array of payment method details collected via the Razorpay PG.
string
Razorpay payment entity id.
string
Payment provider. Always
razorpay.integer
Amount paid via the selected method, in paise.
string
Payment currency. Always
INR.string
Payment method. Values:
card, upi, netbanking, wallet.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.array
Array of bills paid in this transaction.
string
Biller’s bill reference/invoice number. Mandatory in multi-bill scenarios.
integer
Individual bill amount in paise.
string
Bill currency. Always
INR.integer
Bill generation date as a UNIX timestamp.
integer
Bill payment due date as a UNIX timestamp.
string
Billing frequency. Values:
onetime, daily, monthly, quarterly, halfyearly, yearly.object
Additional biller-specific metadata. Dynamic key-value pairs that vary by biller.
string
Error code. Present only when
status is failed. Values: BAD_REQUEST_ERROR, GATEWAY_ERROR, SERVER_ERROR.string
Human-readable error description.
string
Where the error originated. Values:
customer, biller, gateway, razorpay.string
Step at which the error occurred. For example,
bill_payment, validation.string
Programmatic error reason code. Use this for error-specific handling logic.
object
Additional context such as payment ids and gateway error codes.
integer
UNIX timestamp when the bill payment was created.
Errors
The bill payment id is invalid or not found.
The bill payment id is invalid or not found.
Code:
400No bill payment was found for the provided id.Solution: Verify the id matches the one returned by the Create a Bill Payment API.The API <key/secret> provided is invalid.
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
Was this page helpful?