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 attempt to return the final result within a 30-second window in the same call. If the result is not ready within that window, the API falls back to the standard async flow and returns HTTP 202.

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.

Response status

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.

For LIST billers where the Bill Fetch Response was returned using x-api-version: 2026-01-01, data.result contains the biller_responses array format. For all other billers, it contains the standard biller_response object.

Examples

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 35 seconds for the Bill Fetch Request and Bill Payment Request APIs. This ensures your client does not time out before the 30-second sync window closes.
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.

Recovery after a client timeout

If your client times out before the response arrives, the payment may still be processing on the server. The Cashfree server keeps the connection open for up to 60 seconds. If the sync result is not ready within the 30-second window, the API immediately sends an async fallback response in the same call. This response contains transaction_ref_id. Use that transaction_ref_id to poll the Bill Payment Response API for the final status. Cashfree delivers webhook notifications for bill fetch and payment events regardless of whether the API returned HTTP 200 (synchronous result) or HTTP 202 (asynchronous). You receive webhooks in both cases, so your webhook handler does not need any changes when synchronous responses are enabled. For payload contracts and signature verification, see COU Webhooks.

BBPS for Business

BBPS for Customers

Response status

Examples

Handle synchronous responses

Recovery after a client timeout

​Response status

​Examples

​Handle synchronous responses

​Recovery after a client timeout

Response status

Examples

Handle synchronous responses

Recovery after a client timeout