> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# BBPS for Customers

> API reference for Cashfree BBPS for Customers covering authentication, rate limits, bill payment flow, biller discovery, bill fetch, bill payment, complaints, and wallet operations.

The BBPS for Customers (Customer Operating Unit, or COU) APIs enable Agent Institutions, entities that onboard customers and offer BBPS services, to integrate with the Bharat Bill Payment System (BBPS) network operated by NPCI. Using these APIs, Agent Institutions can build complete bill payment experiences for their customers across all registered BBPS billers.

## Key features

Cashfree BBPS for Customers supports the following capabilities:

* **Biller discovery**: Retrieve all active biller categories and MDM details, including customer input parameters, supported payment modes, and fee structures, to present accurate biller information before initiating a payment.
* **Async bill fetch and payment**: Bill fetch and payment requests return a reference ID immediately. Poll the response endpoint until the operation completes.
* **Flexible payment flows**: Supports both `FETCH_AND_PAY` and `VALIDATE_AND_PAY` flows, determined automatically by biller configuration, across all BBPS categories.
* **Complaint and dispute management**: Raise complaints or check the status of any processed transaction using the Transaction Status and Complaint APIs.
* **Wallet management**: Check the agent wallet balance and retrieve paginated ledger history for reconciliation.

## Authentication

All APIs use header authentication. Pass both headers in every request:

```http theme={"dark"}
x-client-id: <your-client-id>
x-client-secret: <your-client-secret>
```

<Note>
  Credentials are issued per Agent Institution. Your `x-client-id` and `x-client-secret` are available in your [Merchant Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys) for both sandbox and production environments.
</Note>

## Rate limits

The following rate limits apply to biller discovery APIs:

| API                     | Limit                       |
| ----------------------- | --------------------------- |
| Fetch biller categories | 100 requests per 60 seconds |
| Fetch billers info      | 100 requests per 60 seconds |

Exceeding the limit returns HTTP 429. Since biller data changes infrequently, cache it at predefined intervals rather than calling on every user request.

## API flow

A complete bill payment journey involves the following steps:

<Steps>
  <Step title="Fetch biller categories">
    Get the list of active biller categories, for example, ELECTRICITY, DTH, and GAS. Cache this list because it rarely changes.
  </Step>

  <Step title="Fetch billers info">
    Get MDM details for billers in a category, including customer input parameters, supported payment modes, fetch requirements, and fee structures.
  </Step>

  <Step title="Bill fetch request">
    Initiate an async bill fetch or validation for the customer. Returns a `ref_id` immediately. The system determines the flow automatically based on biller configuration:

    * `FETCH_AND_PAY` returns bill details from the biller
    * `VALIDATE_AND_PAY` validates customer identity without fetching bill details
  </Step>

  <Step title="Poll bill fetch response">
    Poll using the `ref_id` until the response is no longer `"Request is still being processed"`.
  </Step>

  <Step title="Bill payment request">
    Submit the payment using data from the fetch response. Returns `transaction_ref_id` immediately.
  </Step>

  <Step title="Poll bill payment response">
    Poll using `bill_fetch_ref_id` and `transaction_ref_id` until `data.status` is `"success"` or `"failed"`.
  </Step>
</Steps>

<Note>
  For complaints or transaction status checks, use the Transaction Status and Complaint Request API after a payment is processed.
</Note>

<Tabs>
  <Tab title="Billers">
    <div class="row relative lowmhr">
      <div class="col-md-6">
        <div>
          <h4 class="text-gray-800 semibold dark:text-gray-500 pb-4">Billers</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/billers/categories" class="text-cf bold">Fetch biller categories</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Get all active biller category codes, such as ELECTRICITY, DTH, and GAS. Cache this list because it changes infrequently.
            </p>
          </div>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/billers/info" class="text-cf bold">Fetch billers info</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Get MDM details for billers in a category, including customer input parameters, supported payment modes, fetch requirements, and fee structures.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Bill fetch">
    <div class="row relative lowmhr">
      <div class="col-md-6">
        <div>
          <h4 class="text-gray-800 semibold dark:text-gray-500 pb-4">Bill fetch</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-fetch/request" class="text-cf bold">Bill fetch request</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Initiate an async bill fetch or validation for the customer. Returns a <code>ref\_id</code> immediately. The system determines the flow based on biller configuration. It uses <code>FETCH\_AND\_PAY</code> or <code>VALIDATE\_AND\_PAY</code>.
            </p>
          </div>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-fetch/response" class="text-cf bold">Bill fetch response</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Poll for the bill fetch result using the <code>ref\_id</code> returned from the fetch request.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Bill payment">
    <div class="row relative lowmhr">
      <div class="col-md-6">
        <div>
          <h4 class="text-gray-800 semibold dark:text-gray-500 pb-4">Bill payment</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-payment/request" class="text-cf bold">Bill payment request</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Initiate an async bill payment using data from the fetch response. Returns a <code>transaction\_ref\_id</code> immediately.
            </p>
          </div>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/bill-payment/response" class="text-cf bold">Bill payment response</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Poll for the payment result using <code>bill\_fetch\_ref\_id</code> and <code>transaction\_ref\_id</code> until <code>data.status</code> is <code>success</code> or <code>failed</code>.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Complaints">
    <div class="row relative lowmhr">
      <div class="col-md-6">
        <div>
          <h4 class="text-gray-800 semibold dark:text-gray-500 pb-4">Complaints and transaction status</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/complaint/request" class="text-cf bold">Transaction status and complaint request</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Raise a complaint or check the status of a processed transaction.
            </p>
          </div>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/complaint/response" class="text-cf bold">Transaction status and complaint response</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Poll for the complaint or transaction status result.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

  <Tab title="Wallet">
    <div class="row relative lowmhr">
      <div class="col-md-6">
        <div>
          <h4 class="text-gray-800 semibold dark:text-gray-500 pb-4">Wallet</h4>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/wallet/balance" class="text-cf bold">Wallet balance</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Get the current agent wallet balance.
            </p>
          </div>

          <div>
            <a href="/docs/api-reference/other-apis/bbps-cou/wallet/ledger" class="text-cf bold">Wallet ledger</a>

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Retrieve paginated wallet transaction history for reconciliation.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>
</Tabs>