> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
</div>

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

<Info>
  **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.
</Info>

<Warning>
  **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.
</Warning>

<Info>
  **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.
</Info>

<RequestExample>
  ```bash Curl theme={null}
  curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
  -X GET https://api.razorpay.com/v1/bill_payments/payments/bill_pay_xxxx
  ```
</RequestExample>

<ResponseExample>
  ```json status: success theme={null}
  {
    "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
  }
  ```

  ```json status: pending theme={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
  }
  ```

  ```json status: failed theme={null}
  {
    "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"
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
      "code": "BAD_REQUEST_ERROR",
      "description": "The bill payment id is invalid",
      "source": "NA",
      "step": "NA",
      "reason": "NA",
      "metadata": {}
    }
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the bill payment returned by [Create a Bill Payment](/docs/api/bills/bill-payments/create-bill-payment). For example, `bill_pay_xxxx`.
</ParamField>

## Response Parameters

<ResponseField name="id" type="string">
  Razorpay's unique bill payment transaction id.
</ResponseField>

<ResponseField name="entity" type="string">
  Indicates the type of entity. Always `bill_payment.payment`.
</ResponseField>

<ResponseField name="status" type="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_*`](/docs/errors/bbps/list) fields for details.
</ResponseField>

<ResponseField name="gateway" type="string">
  Payment gateway. Always `bbps`.
</ResponseField>

<ResponseField name="gateway_transaction_id" type="string">
  BBPS/NPCI transaction reference id. Fixed length of 12 or 20 characters. Store this for reconciliation, settlement tracking and dispute resolution.
</ResponseField>

<ResponseField name="biller_id" type="string">
  Razorpay biller entity id.
</ResponseField>

<ResponseField name="gateway_biller_id" type="string">
  NPCI's biller id.
</ResponseField>

<ResponseField name="biller_transaction_id" type="string">
  Biller's internal transaction/receipt reference number. Present only when `status` is `success`. Share this with the customer as their BBPS payment reference.
</ResponseField>

<ResponseField name="direct_pay" type="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.
</ResponseField>

<ResponseField name="bill_pay_amount" type="integer">
  Total bill amount paid in paise, excluding fees.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency. Always `INR`.
</ResponseField>

<ResponseField name="fees" type="object">
  Fee breakdown.
</ResponseField>

<ResponseField name="fees.app_convenience_fee" type="integer">
  App/platform convenience fee charged to the customer, in paise.
</ResponseField>

<ResponseField name="fees.biller_convenience_fee" type="integer">
  Customer Convenience Fee (CCF) charged by the biller, in paise.
</ResponseField>

<ResponseField name="customer" type="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.
</ResponseField>

<ResponseField name="customer.id" type="string">
  Dynamic key-value pair holding your customer reference. Echoed back exactly as sent in the request. Not validated by Razorpay.
</ResponseField>

<ResponseField name="customer.name" type="string">
  Dynamic key-value pair holding the customer name. Echoed back exactly as sent in the request. Not validated by Razorpay.
</ResponseField>

<ResponseField name="customer.mobile" type="string" required>
  Customer's mobile number with country code. For example, `919000090000`.
</ResponseField>

<ResponseField name="customer.email" type="string">
  Dynamic key-value pair holding the customer email. Echoed back exactly as sent in the request. Not validated by Razorpay.
</ResponseField>

<ResponseField name="payment" type="array">
  Array of payment method details collected via the Razorpay PG.
</ResponseField>

<ResponseField name="payment[].id" type="string">
  Razorpay payment entity id.
</ResponseField>

<ResponseField name="payment[].provider" type="string">
  Payment provider. Always `razorpay`.
</ResponseField>

<ResponseField name="payment[].amount" type="integer">
  Amount paid via the selected method, in paise.
</ResponseField>

<ResponseField name="payment[].currency" type="string">
  Payment currency. Always `INR`.
</ResponseField>

<ResponseField name="payment[].method" type="string">
  Payment method. Values: `card`, `upi`, `netbanking`, `wallet`.
</ResponseField>

<ResponseField name="account_holder" type="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.
</ResponseField>

<ResponseField name="bills" type="array">
  Array of bills paid in this transaction.
</ResponseField>

<ResponseField name="bills[].bill_number" type="string">
  Biller's bill reference/invoice number. Mandatory in multi-bill scenarios.
</ResponseField>

<ResponseField name="bills[].amount" type="integer">
  Individual bill amount in paise.
</ResponseField>

<ResponseField name="bills[].currency" type="string">
  Bill currency. Always `INR`.
</ResponseField>

<ResponseField name="bills[].bill_date" type="integer">
  Bill generation date as a UNIX timestamp.
</ResponseField>

<ResponseField name="bills[].due_date" type="integer">
  Bill payment due date as a UNIX timestamp.
</ResponseField>

<ResponseField name="bills[].bill_period" type="string">
  Billing frequency. Values: `onetime`, `daily`, `monthly`, `quarterly`, `halfyearly`, `yearly`.
</ResponseField>

<ResponseField name="data" type="object">
  Additional biller-specific metadata. Dynamic key-value pairs that vary by biller.
</ResponseField>

<ResponseField name="error_code" type="string">
  Error code. Present only when `status` is `failed`. Values: `BAD_REQUEST_ERROR`, `GATEWAY_ERROR`, `SERVER_ERROR`.
</ResponseField>

<ResponseField name="error_description" type="string">
  Human-readable error description.
</ResponseField>

<ResponseField name="error_source" type="string">
  Where the error originated. Values: `customer`, `biller`, `gateway`, `razorpay`.
</ResponseField>

<ResponseField name="error_step" type="string">
  Step at which the error occurred. For example, `bill_payment`, `validation`.
</ResponseField>

<ResponseField name="error_reason" type="string">
  Programmatic error reason code. Use this for error-specific handling logic.
</ResponseField>

<ResponseField name="error_metadata" type="object">
  Additional context such as payment ids and gateway error codes.
</ResponseField>

<ResponseField name="created_at" type="integer">
  UNIX timestamp when the bill payment was created.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion
    title="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.
  </Accordion>
</AccordionGroup>