Skip to main content
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:
Credentials are issued per Agent Institution. Your x-client-id and x-client-secret are available in your Merchant Dashboard for both sandbox and production environments.

​
Versioning

All BBPS COU APIs require an x-api-version header in every request. The current supported version is 2025-01-01.
This value is pre-filled in the Try It playground on each API page.

​
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:
1

Fetch biller categories

Get the list of active biller categories, for example, ELECTRICITY, DTH, and GAS.
2

Fetch billers info

Get MDM details for billers in a category, including customer input parameters, supported payment modes, fetch requirements, and fee structures.
3

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
4

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

Bill payment request

Submit the payment using data from the fetch response. Returns transaction_ref_id immediately.
6

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

​
Billers

Fetch biller categories

Get all active biller category codes, such as ELECTRICITY, DTH, and GAS. Cache this list because it changes infrequently.

Fetch billers info

Get MDM details for billers in a category, including customer input parameters, supported payment modes, fetch requirements, and fee structures.