Skip to main content

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.

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: 
x-client-id: <your-client-id>
x-client-secret: <your-client-secret>
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.

ā€‹
Rate limits

The following rate limits apply to biller discovery APIs:
APILimit
Fetch biller categories100 requests per 60 seconds
Fetch billers info100 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:
1

Fetch biller categories

Get the list of active biller categories, for example, ELECTRICITY, DTH, and GAS. Cache this list because it rarely changes.
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 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
4

Poll bill fetch response

Poll using the ref_id until the response is no longer "Request is still being processed".
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 until data.status is "success" or "failed".
For complaints or transaction status checks, use the Transaction Status and Complaint Request API after a payment is processed.

ā€‹
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.