BBPS COU APIs | Cashfree

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: By default, 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.
Synchronous responses: Optionally, receive the final bill fetch, validation, or payment result in the same API call, without polling.
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:

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.

Versioning

All BBPS COU APIs require an x-api-version header in every request. The current supported version is 2025-01-01.

x-api-version: 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.

Synchronous responses

By default, the Bill Fetch Request and Bill Payment Request APIs are asynchronous. They return HTTP 202, and you poll the corresponding response API for the final result. With synchronous responses enabled, these APIs return the final result directly in the response, so you do not need to poll. If the result is not ready within the synchronous wait period, the API returns HTTP 202 as usual.

Synchronous responses are an opt-in feature and are disabled by default. To enable them for your account, contact your Cashfree account manager. You do not need to change your request format.

The following table explains each response status and what to do:

HTTP status	What it means	What to do
`200`	The final result is ready. The `data.status` field is `SUCCESS` or `FAILED`, and `data.result` contains the details.	Read the result from `data.result`. Do not poll.
`202`	The request is still being processed. The `data.status` field is `PROCESSING`.	Poll the Bill Fetch Response API or the Bill Payment Response API for the final result.

The data.result object has the same format as the data object that the corresponding response API returns, so you can reuse your existing response handling. The following examples show Bill Payment Request responses for each outcome:

{
  "status": "OK",
  "message": "Payment successful",
  "data": {
    "bill_fetch_ref_id": "c6f776ec8a694014a823b48314962450433",
    "transaction_ref_id": "CH0162455XTQK9MIPNYZ",
    "status": "SUCCESS",
    "result": {
      "bill_payment_response": {
        "head": {
          "bill_fetch_ref_id": "c6f776ec8a694014a823b48314962450433"
        },
        "reason": {
          "approval_ref_num": "7E81EE99F88A498CAD5B6DB9246A63F2",
          "response_code": "000",
          "response_reason": "Successful",
          "compliance_resp_cd": "",
          "compliance_reason": ""
        },
        "txn": {
          "transaction_ref_id": "CH0162455XTQK9MIPNYZ"
        },
        "bill_details": {
          "customer_params": {
            "tag": [
              {
                "name": "Loan Account Number",
                "value": "LN0098766582"
              },
              {
                "name": "Mobile Number",
                "value": "7428776582"
              }
            ]
          }
        },
        "biller_response": {
          "customer_name": "Rahul Kumar",
          "amount": "250.00",
          "cust_conv_fee": "0.00",
          "due_date": "2026-07-31",
          "bill_date": "2026-07-20",
          "bill_number": "SWAR_REF_TEST_6582",
          "bill_period": "MONTHLY",
          "tag": null
        },
        "additional_info": null
      }
    }
  }
}

{
  "status": "OK",
  "message": "Payment failed",
  "data": {
    "bill_fetch_ref_id": "9a9dd6cd75b14d65907a1babfaf62440909",
    "transaction_ref_id": "CH0162440OP9HB5C7NZN",
    "status": "FAILED",
    "result": {
      "bill_payment_response": {
        "head": {
          "bill_fetch_ref_id": "9a9dd6cd75b14d65907a1babfaf62440909"
        },
        "reason": {
          "approval_ref_num": "",
          "response_code": "",
          "response_reason": "Failure",
          "compliance_resp_cd": "",
          "compliance_reason": "ERR023 : The request is duplicate:RefId,MsgId and TxnReferenceId should have unique values"
        },
        "txn": {
          "transaction_ref_id": "CH0162440OP9HB5C7NZN"
        },
        "bill_details": null,
        "biller_response": null,
        "additional_info": null
      }
    }
  }
}

{
  "status": "ACCEPTED",
  "message": "Bill payment request accepted for processing",
  "data": {
    "bill_fetch_ref_id": "c6f776ec8a694014a823b48314962450433",
    "transaction_ref_id": "CH0162455XTQK9MIPNYZ",
    "status": "PROCESSING"
  }
}

Handle synchronous responses

Even with synchronous responses enabled, some requests return HTTP 202, for example when the biller responds slowly. To handle both outcomes:

Set your HTTP client timeout to at least 30 seconds for the Bill Fetch Request and Bill Payment Request APIs.
Check the HTTP status code of the response.
If the status code is 200, read the final status from data.status and the details from data.result.
If the status code is 202, poll the corresponding response API using the polling strategy described on its page.

Do not resend a Bill Payment Request after a client timeout or an HTTP 202 response. Resending the request can create a duplicate payment. After an HTTP 202 response, poll the Bill Payment Response API for the final status.

Cashfree delivers webhooks as usual, whether the API returns HTTP 200 or HTTP 202. For details, see COU Webhooks.

API flow

A complete bill payment journey involves the following steps:

Fetch biller categories

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

Fetch billers info

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

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

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. If synchronous responses are enabled and the Bill Fetch Request API returned HTTP 200, skip this step.

Bill payment request

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

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. If synchronous responses are enabled and the Bill Payment Request API returned HTTP 200, skip this step.

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
Bill fetch and payment
Ticket and wallet

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.

Bill fetch

Bill fetch request

Initiate an async bill fetch or validation for the customer. Returns a ref_id immediately. The system determines the flow based on biller configuration. It uses FETCH_AND_PAY or VALIDATE_AND_PAY.

Bill fetch response

Poll for the bill fetch result using the ref_id returned from the fetch request.

Bill payment

Bill payment request

Initiate an async bill payment using data from the fetch response. Returns a transaction_ref_id immediately.

Bill payment response

Poll for the payment result using bill_fetch_ref_id and transaction_ref_id until data.status is success or failed.

Ticket management

Raise ticket request

Raise a support ticket for a processed bill payment transaction. Returns a ref_id immediately.

Poll ticket status

Poll for the current status of a raised ticket using the ref_id returned from the ticket request.

Wallet

Wallet balance

Get the current agent institution wallet balance.

Wallet ledger

Retrieve paginated wallet transaction history for reconciliation.

​Key features

​Authentication

​Versioning

​Rate limits

​Synchronous responses

​Handle synchronous responses

​API flow

​Billers

​Bill fetch

​Bill payment

​Ticket management

​Wallet

Key features

Authentication

Versioning

Rate limits

Synchronous responses

Handle synchronous responses

API flow

Billers

Bill fetch

Bill payment

Ticket management

Wallet