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

> Cashfree BBPS for Customers APIs cover authentication, biller discovery, bill fetch, bill payment, ticket handling, and wallet operations for Agent Institutions.

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 corresponding response endpoint at regular intervals until the operation returns a terminal status.
* **Flexible payment flows**: Supports `FETCH_AND_PAY`, `VALIDATE_AND_PAY`, and direct bill payment flows, determined automatically by biller configuration, across all BBPS categories. Direct bill payment is used for billers that do not require a prior fetch or validation step, such as donation billers.
* **Ticket management**: Raise a support ticket for any processed transaction and poll its status using the Ticket APIs.
* **Wallet management**: Check the agent institution 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

All APIs are rate limited to 100 requests per 60 seconds. Exceeding the limit returns HTTP 429.

## 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.
  </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, validation, or direct payment 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
    * Direct bill payment skips the fetch step entirely and is used for billers such as donation billers
  </Step>

  <Step title="Poll bill fetch response">
    Poll using the `ref_id` at regular intervals until the response returns a terminal status. Refer to the polling strategy in the Bill fetch response API for recommended intervals and retry limits.
  </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` at regular intervals until the response returns a terminal status. Refer to the polling strategy in the Bill payment response API for recommended intervals and retry limits.
  </Step>
</Steps>

<Note>
  To raise a support ticket for a processed payment, use the Raise Ticket Request API after a payment is complete. Poll the Ticket Status API using the returned `ref_id` to track progress.
</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.
            </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 the response returns a terminal status.
            </p>
          </div>
        </div>
      </div>
    </div>
  </Tab>

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

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

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Raise a support ticket for a processed bill payment transaction. Returns a <code>ref\_id</code> immediately.
            </p>
          </div>

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

            <p style={{marginBottom: '1rem'}} class="text-gray-500 dark:text-gray-500">
              Poll for the current status of a raised ticket using the <code>ref\_id</code> returned from the ticket request.
            </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 institution 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>