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

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

status: success

{
  "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": "[e-mail]"
  },
  "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
}

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 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.

Curl

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

status: success

{
  "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": "[e-mail]"
  },
  "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
}

Path Parameters

id · string · required

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 · required

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.

Code: 400

No 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.

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.