curl --request POST \
--url https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch \
--header 'Content-Type: application/json' \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>' \
--data '
{
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
}
'import requests
url = "https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch"
payload = { "ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" }
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-client-id': '<api-key>',
'x-client-secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({ref_id: 'HENSVVR4QOS7X1UGPY7JGUV444P10102202'})
};
fetch('https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'ref_id' => 'HENSVVR4QOS7X1UGPY7JGUV444P10102202'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-client-id: <api-key>",
"x-client-secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch"
payload := strings.NewReader("{\n \"ref_id\": \"HENSVVR4QOS7X1UGPY7JGUV444P10102202\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"ref_id\": \"HENSVVR4QOS7X1UGPY7JGUV444P10102202\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"ref_id\": \"HENSVVR4QOS7X1UGPY7JGUV444P10102202\"\n}"
response = http.request(request)
puts response.read_body{
"status": "OK",
"message": "Request is still being processed",
"data": {
"bill_fetch_response": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"response_code": "PENDING",
"response_reason": "Processing"
}
}
}Bill Fetch Response
Use this API to poll the result of a previously initiated Bill Fetch or Bill Validation request.
Use the ref_id from the Bill Fetch Request API to retrieve the status and bill details.
If synchronous responses are enabled for your account and the Bill Fetch Request API returned HTTP 200, the final result is already available in data.result and you do not need to poll. Poll only when the request returned HTTP 202.
Polling strategy
Polling strategy
Poll at increasing intervals until message is no longer "Request is still being processed":
| Attempt | Wait before this poll |
|---|---|
| 1 | 5 seconds |
| 2 | 15 seconds |
| 3 | 30 seconds |
| 4 | 1 minute |
| 5+ | 3 minutes |
Stop polling when message is "Bill details fetched successfully" or "Bill request failed". If the request remains in a processing state beyond your retry limit, treat it as a timeout and raise a support ticket.
Response fields by outcome
Response fields by outcome
bill_fetch_responseis present in every response, including success, failure, and pending states.- For
FETCH_AND_PAYsuccess, the response includesbill_fetch_response,bill_details,biller_responseorbiller_responses(depending on version), andadditional_info. - While the request is pending, the response includes only
bill_fetch_response, with the processing status.
Version differences
Version differences
x-api-version: 2025-01-01(default): on success, the response returnsbiller_response(single object) with the bill details.x-api-version: 2026-10-01: on success, the response returnsbiller_responses(array) for LIST type billers (biller_response_type: LISTin Fetch Billers Info). A LIST biller can return multiple bills in a single fetch — useselection_typefrom Fetch Billers Info to determine whether the customer must pay all bills (ALL), can select one (SINGLE), or can select multiple (MULTIPLE).
curl --request POST \
--url https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch \
--header 'Content-Type: application/json' \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>' \
--data '
{
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202"
}
'import requests
url = "https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch"
payload = { "ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202" }
headers = {
"x-client-id": "<api-key>",
"x-client-secret": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-client-id': '<api-key>',
'x-client-secret': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({ref_id: 'HENSVVR4QOS7X1UGPY7JGUV444P10102202'})
};
fetch('https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'ref_id' => 'HENSVVR4QOS7X1UGPY7JGUV444P10102202'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-client-id: <api-key>",
"x-client-secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch"
payload := strings.NewReader("{\n \"ref_id\": \"HENSVVR4QOS7X1UGPY7JGUV444P10102202\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-client-id", "<api-key>")
req.Header.Add("x-client-secret", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"ref_id\": \"HENSVVR4QOS7X1UGPY7JGUV444P10102202\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cashfree.com/bbps/cou/v1/billers/response/bill-fetch")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-client-id"] = '<api-key>'
request["x-client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"ref_id\": \"HENSVVR4QOS7X1UGPY7JGUV444P10102202\"\n}"
response = http.request(request)
puts response.read_body{
"status": "OK",
"message": "Request is still being processed",
"data": {
"bill_fetch_response": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"response_code": "PENDING",
"response_reason": "Processing"
}
}
}Authorizations
Your unique client identifier issued by Cashfree. You can find this in your Merchant Dashboard.
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
API version to be used. Format is YYYY-MM-DD. Supported versions are 2025-01-01 (default) and 2026-10-01. If not specified, 2025-01-01 is used. The version determines the response structure for bill fetch and payment status — 2025-01-01 returns biller_response (single object), while 2026-10-01 returns biller_responses (array).
2025-01-01, 2026-10-01 Body
Request parameters to poll a bill fetch or bill validation request.
The reference ID received from the Bill Fetch Request API. Used to identify and retrieve the result of the corresponding async request.
"HENSVVR4QOS7X1UGPY7JGUV444P10102202"
Response
Success response for polling a bill fetch or bill validation request.
Always "OK" for all poll responses, regardless of the bill fetch outcome.
"OK"
Terminal or in-progress status of the bill fetch operation. Continue polling while this is "Request is still being processed".
Bill details fetched successfully, Request is still being processed, Bill request failed Response payload. Always contains bill_fetch_response; other fields depend on the flow and outcome.
Show child attributes
Show child attributes
Was this page helpful?