Bill Fetch Request
curl --request POST \
--url https://sandbox.cashfree.com/bbps/cou/v1/billers/request/bill-fetch \
--header 'Content-Type: application/json' \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>' \
--data '
{
"bill_fetch_request": {
"agent_id": "OU01XXXXINT001123456",
"biller_id": "VODA00000MUM03",
"agent_device_info": {
"init_channel": "INTB",
"ip": "124.170.23.22",
"mac": "00-0D-60-07-2A-F0"
},
"customer_info": {
"customer_mobile": "9505XXXX98",
"customer_email": "customer@example.com"
},
"input_params": {
"input": [
{
"param_name": "RefFld1",
"param_value": "9876543210"
},
{
"param_name": "RefFld2",
"param_value": "ABCD123"
}
]
}
}
}
'import requests
url = "https://sandbox.cashfree.com/bbps/cou/v1/billers/request/bill-fetch"
payload = { "bill_fetch_request": {
"agent_id": "OU01XXXXINT001123456",
"biller_id": "VODA00000MUM03",
"agent_device_info": {
"init_channel": "INTB",
"ip": "124.170.23.22",
"mac": "00-0D-60-07-2A-F0"
},
"customer_info": {
"customer_mobile": "9505XXXX98",
"customer_email": "customer@example.com"
},
"input_params": { "input": [
{
"param_name": "RefFld1",
"param_value": "9876543210"
},
{
"param_name": "RefFld2",
"param_value": "ABCD123"
}
] }
} }
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({
bill_fetch_request: {
agent_id: 'OU01XXXXINT001123456',
biller_id: 'VODA00000MUM03',
agent_device_info: {init_channel: 'INTB', ip: '124.170.23.22', mac: '00-0D-60-07-2A-F0'},
customer_info: {customer_mobile: '9505XXXX98', customer_email: 'customer@example.com'},
input_params: {
input: [
{param_name: 'RefFld1', param_value: '9876543210'},
{param_name: 'RefFld2', param_value: 'ABCD123'}
]
}
}
})
};
fetch('https://sandbox.cashfree.com/bbps/cou/v1/billers/request/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/request/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([
'bill_fetch_request' => [
'agent_id' => 'OU01XXXXINT001123456',
'biller_id' => 'VODA00000MUM03',
'agent_device_info' => [
'init_channel' => 'INTB',
'ip' => '124.170.23.22',
'mac' => '00-0D-60-07-2A-F0'
],
'customer_info' => [
'customer_mobile' => '9505XXXX98',
'customer_email' => 'customer@example.com'
],
'input_params' => [
'input' => [
[
'param_name' => 'RefFld1',
'param_value' => '9876543210'
],
[
'param_name' => 'RefFld2',
'param_value' => 'ABCD123'
]
]
]
]
]),
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/request/bill-fetch"
payload := strings.NewReader("{\n \"bill_fetch_request\": {\n \"agent_id\": \"OU01XXXXINT001123456\",\n \"biller_id\": \"VODA00000MUM03\",\n \"agent_device_info\": {\n \"init_channel\": \"INTB\",\n \"ip\": \"124.170.23.22\",\n \"mac\": \"00-0D-60-07-2A-F0\"\n },\n \"customer_info\": {\n \"customer_mobile\": \"9505XXXX98\",\n \"customer_email\": \"customer@example.com\"\n },\n \"input_params\": {\n \"input\": [\n {\n \"param_name\": \"RefFld1\",\n \"param_value\": \"9876543210\"\n },\n {\n \"param_name\": \"RefFld2\",\n \"param_value\": \"ABCD123\"\n }\n ]\n }\n }\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/request/bill-fetch")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"bill_fetch_request\": {\n \"agent_id\": \"OU01XXXXINT001123456\",\n \"biller_id\": \"VODA00000MUM03\",\n \"agent_device_info\": {\n \"init_channel\": \"INTB\",\n \"ip\": \"124.170.23.22\",\n \"mac\": \"00-0D-60-07-2A-F0\"\n },\n \"customer_info\": {\n \"customer_mobile\": \"9505XXXX98\",\n \"customer_email\": \"customer@example.com\"\n },\n \"input_params\": {\n \"input\": [\n {\n \"param_name\": \"RefFld1\",\n \"param_value\": \"9876543210\"\n },\n {\n \"param_name\": \"RefFld2\",\n \"param_value\": \"ABCD123\"\n }\n ]\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cashfree.com/bbps/cou/v1/billers/request/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 \"bill_fetch_request\": {\n \"agent_id\": \"OU01XXXXINT001123456\",\n \"biller_id\": \"VODA00000MUM03\",\n \"agent_device_info\": {\n \"init_channel\": \"INTB\",\n \"ip\": \"124.170.23.22\",\n \"mac\": \"00-0D-60-07-2A-F0\"\n },\n \"customer_info\": {\n \"customer_mobile\": \"9505XXXX98\",\n \"customer_email\": \"customer@example.com\"\n },\n \"input_params\": {\n \"input\": [\n {\n \"param_name\": \"RefFld1\",\n \"param_value\": \"9876543210\"\n },\n {\n \"param_name\": \"RefFld2\",\n \"param_value\": \"ABCD123\"\n }\n ]\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"status": "OK",
"message": "Bill details fetched successfully",
"data": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status": "SUCCESS",
"flow": "FETCH_AND_PAY",
"result": {
"bill_fetch_response": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"approval_ref_num": "AB123456",
"response_code": "000",
"response_reason": "Successful"
},
"bill_details": {
"customer_params": {
"tag": [
{
"name": "RefFld1",
"value": "9876543210"
}
]
}
},
"biller_response": {
"customer_name": "Manoj Chekuri",
"amount": "1200.00",
"due_date": "2021-09-24",
"bill_date": "2021-01-02",
"bill_number": "1232332",
"bill_period": "MONTHLY"
},
"additional_info": {
"tag": [
{
"name": "BlRspFld1",
"value": "someValue"
}
]
}
}
}
}
Bill Fetch
Bill Fetch Request
Use this API to initiate a bill fetch or bill validation request for a customer.
By default, this is an async API. It returns an acknowledgement with a ref_id and HTTP 202.
Retrieve the bill details by polling the Bill Fetch Response API using this ref_id.
If synchronous responses are enabled for your account, this API returns the final result directly with HTTP 200. The result is in data.result, in the same format as the data object of the Bill Fetch Response API. If the result is not ready within the synchronous wait period, the API returns HTTP 202 and you poll as usual. For details, see Synchronous responses.
With synchronous responses enabled, handle both HTTP 200 and HTTP 202, and set your HTTP client timeout to at least 30 seconds.
This API is only applicable for billers whose fetch_requirement or support_bill_validation is MANDATORY or OPTIONAL. For billers where both are NOT_SUPPORTED (i.e., DIRECT_PAY flow), calling this API will return a validation error. Proceed directly to the Bill Payment Request API for those billers.
Flow determination logic
Flow determination logic
The flow is determined using fetch_requirement and support_bill_validation from the Fetch Billers Info API response, evaluated in the following priority order:
| Priority | fetch_requirement | support_bill_validation | Flow |
|---|---|---|---|
| 1 | MANDATORY | Any | FETCH_AND_PAY |
| 2 | NOT_SUPPORTED | MANDATORY or OPTIONAL | VALIDATE_AND_PAY |
| 3 | NOT_SUPPORTED | NOT_SUPPORTED | DIRECT_PAY |
| 4 | OPTIONAL | MANDATORY | VALIDATE_AND_PAY |
| 5 | OPTIONAL | Any other | FETCH_AND_PAY |
For DIRECT_PAY, skip the bill fetch step and proceed directly to the Bill Payment Request API.
Store the flow field from the response. It determines which fields to expect in the Bill Fetch Response and whether a bill payment can proceed without a prior fetch.
POST
/
bbps
/
cou
/
v1
/
billers
/
request
/
bill-fetch
Bill Fetch Request
curl --request POST \
--url https://sandbox.cashfree.com/bbps/cou/v1/billers/request/bill-fetch \
--header 'Content-Type: application/json' \
--header 'x-client-id: <api-key>' \
--header 'x-client-secret: <api-key>' \
--data '
{
"bill_fetch_request": {
"agent_id": "OU01XXXXINT001123456",
"biller_id": "VODA00000MUM03",
"agent_device_info": {
"init_channel": "INTB",
"ip": "124.170.23.22",
"mac": "00-0D-60-07-2A-F0"
},
"customer_info": {
"customer_mobile": "9505XXXX98",
"customer_email": "customer@example.com"
},
"input_params": {
"input": [
{
"param_name": "RefFld1",
"param_value": "9876543210"
},
{
"param_name": "RefFld2",
"param_value": "ABCD123"
}
]
}
}
}
'import requests
url = "https://sandbox.cashfree.com/bbps/cou/v1/billers/request/bill-fetch"
payload = { "bill_fetch_request": {
"agent_id": "OU01XXXXINT001123456",
"biller_id": "VODA00000MUM03",
"agent_device_info": {
"init_channel": "INTB",
"ip": "124.170.23.22",
"mac": "00-0D-60-07-2A-F0"
},
"customer_info": {
"customer_mobile": "9505XXXX98",
"customer_email": "customer@example.com"
},
"input_params": { "input": [
{
"param_name": "RefFld1",
"param_value": "9876543210"
},
{
"param_name": "RefFld2",
"param_value": "ABCD123"
}
] }
} }
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({
bill_fetch_request: {
agent_id: 'OU01XXXXINT001123456',
biller_id: 'VODA00000MUM03',
agent_device_info: {init_channel: 'INTB', ip: '124.170.23.22', mac: '00-0D-60-07-2A-F0'},
customer_info: {customer_mobile: '9505XXXX98', customer_email: 'customer@example.com'},
input_params: {
input: [
{param_name: 'RefFld1', param_value: '9876543210'},
{param_name: 'RefFld2', param_value: 'ABCD123'}
]
}
}
})
};
fetch('https://sandbox.cashfree.com/bbps/cou/v1/billers/request/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/request/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([
'bill_fetch_request' => [
'agent_id' => 'OU01XXXXINT001123456',
'biller_id' => 'VODA00000MUM03',
'agent_device_info' => [
'init_channel' => 'INTB',
'ip' => '124.170.23.22',
'mac' => '00-0D-60-07-2A-F0'
],
'customer_info' => [
'customer_mobile' => '9505XXXX98',
'customer_email' => 'customer@example.com'
],
'input_params' => [
'input' => [
[
'param_name' => 'RefFld1',
'param_value' => '9876543210'
],
[
'param_name' => 'RefFld2',
'param_value' => 'ABCD123'
]
]
]
]
]),
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/request/bill-fetch"
payload := strings.NewReader("{\n \"bill_fetch_request\": {\n \"agent_id\": \"OU01XXXXINT001123456\",\n \"biller_id\": \"VODA00000MUM03\",\n \"agent_device_info\": {\n \"init_channel\": \"INTB\",\n \"ip\": \"124.170.23.22\",\n \"mac\": \"00-0D-60-07-2A-F0\"\n },\n \"customer_info\": {\n \"customer_mobile\": \"9505XXXX98\",\n \"customer_email\": \"customer@example.com\"\n },\n \"input_params\": {\n \"input\": [\n {\n \"param_name\": \"RefFld1\",\n \"param_value\": \"9876543210\"\n },\n {\n \"param_name\": \"RefFld2\",\n \"param_value\": \"ABCD123\"\n }\n ]\n }\n }\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/request/bill-fetch")
.header("x-client-id", "<api-key>")
.header("x-client-secret", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"bill_fetch_request\": {\n \"agent_id\": \"OU01XXXXINT001123456\",\n \"biller_id\": \"VODA00000MUM03\",\n \"agent_device_info\": {\n \"init_channel\": \"INTB\",\n \"ip\": \"124.170.23.22\",\n \"mac\": \"00-0D-60-07-2A-F0\"\n },\n \"customer_info\": {\n \"customer_mobile\": \"9505XXXX98\",\n \"customer_email\": \"customer@example.com\"\n },\n \"input_params\": {\n \"input\": [\n {\n \"param_name\": \"RefFld1\",\n \"param_value\": \"9876543210\"\n },\n {\n \"param_name\": \"RefFld2\",\n \"param_value\": \"ABCD123\"\n }\n ]\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cashfree.com/bbps/cou/v1/billers/request/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 \"bill_fetch_request\": {\n \"agent_id\": \"OU01XXXXINT001123456\",\n \"biller_id\": \"VODA00000MUM03\",\n \"agent_device_info\": {\n \"init_channel\": \"INTB\",\n \"ip\": \"124.170.23.22\",\n \"mac\": \"00-0D-60-07-2A-F0\"\n },\n \"customer_info\": {\n \"customer_mobile\": \"9505XXXX98\",\n \"customer_email\": \"customer@example.com\"\n },\n \"input_params\": {\n \"input\": [\n {\n \"param_name\": \"RefFld1\",\n \"param_value\": \"9876543210\"\n },\n {\n \"param_name\": \"RefFld2\",\n \"param_value\": \"ABCD123\"\n }\n ]\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"status": "OK",
"message": "Bill details fetched successfully",
"data": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status": "SUCCESS",
"flow": "FETCH_AND_PAY",
"result": {
"bill_fetch_response": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"approval_ref_num": "AB123456",
"response_code": "000",
"response_reason": "Successful"
},
"bill_details": {
"customer_params": {
"tag": [
{
"name": "RefFld1",
"value": "9876543210"
}
]
}
},
"biller_response": {
"customer_name": "Manoj Chekuri",
"amount": "1200.00",
"due_date": "2021-09-24",
"bill_date": "2021-01-02",
"bill_number": "1232332",
"bill_period": "MONTHLY"
},
"additional_info": {
"tag": [
{
"name": "BlRspFld1",
"value": "someValue"
}
]
}
}
}
}
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).
Available options:
2025-01-01, 2026-10-01 Body
application/json
Request parameters to initiate a bill fetch or bill validation request.
Show child attributes
Show child attributes
Response
Final result returned in the same call. Returned only when synchronous responses are enabled for your account and the result is ready within the synchronous wait period.
Always "OK" when the final result is returned.
Example:
"OK"
Final outcome of the bill fetch or bill validation request. The possible values match the message values that the Bill Fetch Response API returns.
Available options:
Bill details fetched successfully, Bill request failed Acknowledgement fields together with the final result.
Show child attributes
Show child attributes
Was this page helpful?