Bill Payment Response

Use this API to poll for the result of a previously submitted bill payment request. Call this using both bill_fetch_ref_id and transaction_ref_id from the Bill Payment Request API.

Polling strategy

Poll at increasing intervals until data.status is no longer "PROCESSING":

Attempt	Wait before this poll
1	5 seconds
2	15 seconds
3	30 seconds
4	1 minute
5+	3 minutes

Stop polling when data.status is "SUCCESS" or "FAILED". If the payment remains in a processing state beyond your retry limit, treat it as a timeout and raise a support ticket.

Response outcomes by `data.status`

• PROCESSING: Payment is still in progress. Continue polling.
• SUCCESS: Payment completed successfully.
• FAILED: Payment failed.

POST /bbps/cou/v1/billers/response/bill-payment

Bill Payment Response (Polling)

cURL

curl --request POST \
  --url https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "bill_fetch_ref_id": "REF20240501ABC123",
  "transaction_ref_id": "TXN20240501XYZ789"
}
'

200

pending

{
  "status": "OK",
  "message": "Payment is still being processed",
  "data": {
    "status": "PROCESSING",
    "response": {
      "bill_payment_response": {
        "head": {
          "bill_fetch_ref_id": "REF20240501ABC123"
        },
        "reason": {
          "response_code": "PENDING",
          "response_reason": "Processing"
        },
        "txn": {
          "transaction_ref_id": "TXN20240501XYZ789"
        }
      }
    }
  }
}

Authorizations

x-client-id · string · header · required

Your unique client identifier issued by Cashfree. You can find this in your Merchant Dashboard.

x-client-secret · string · header · required

Your unique client secret issued by Cashfree. Keep this confidential and never expose it in client-side code. You can find this in your Merchant Dashboard.

Headers

x-api-version · string · default: 2025-01-01 · required

API version to be used. Format is YYYY-MM-DD.

Body

application/json

Request parameters to poll a bill payment request.

bill_fetch_ref_id · string · required

The bill_fetch_ref_id received in the Bill Payment Request API response (data.bill_fetch_ref_id). Used to identify the original bill fetch.

Example:

"REF20240501ABC123"

transaction_ref_id · string · required

The transaction_ref_id received in the Bill Payment Request API response (data.transaction_ref_id). Used to identify this specific payment transaction.

Example:

"TXN20240501XYZ789"

Response

200

application/json

Success response for polling a bill payment request.

status · string

Always "OK" for all poll responses, regardless of the payment outcome.

Example:

"OK"

message · string

Human-readable description of the current payment state.

Example:

"Payment successful"

data · object

Response payload containing the payment status and full transaction details.

Show child attributes