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-api-version: <x-api-version>' \
--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": "INT",
"ip": "124.170.23.22",
"mobile": "9830098300",
"geo_code": "12.9667,77.5667",
"postal_code": "400063"
},
"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": "INT",
"ip": "124.170.23.22",
"mobile": "9830098300",
"geo_code": "12.9667,77.5667",
"postal_code": "400063"
},
"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-api-version": "<x-api-version>",
"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-api-version': '<x-api-version>',
'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: 'INT',
ip: '124.170.23.22',
mobile: '9830098300',
geo_code: '12.9667,77.5667',
postal_code: '400063'
},
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' => 'INT',
'ip' => '124.170.23.22',
'mobile' => '9830098300',
'geo_code' => '12.9667,77.5667',
'postal_code' => '400063'
],
'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-api-version: <x-api-version>",
"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\": \"INT\",\n \"ip\": \"124.170.23.22\",\n \"mobile\": \"9830098300\",\n \"geo_code\": \"12.9667,77.5667\",\n \"postal_code\": \"400063\"\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-api-version", "<x-api-version>")
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-api-version", "<x-api-version>")
.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\": \"INT\",\n \"ip\": \"124.170.23.22\",\n \"mobile\": \"9830098300\",\n \"geo_code\": \"12.9667,77.5667\",\n \"postal_code\": \"400063\"\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-api-version"] = '<x-api-version>'
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\": \"INT\",\n \"ip\": \"124.170.23.22\",\n \"mobile\": \"9830098300\",\n \"geo_code\": \"12.9667,77.5667\",\n \"postal_code\": \"400063\"\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": "ACCEPTED",
"message": "Bill fetch request accepted for processing",
"data": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status": "PROCESSING",
"flow": "FETCH_AND_PAY"
}
}{
"message": "bill_fetch_request.agent_id : is missing in the request. Value received: ",
"code": "bill_fetch_request.agent_id_missing",
"type": "invalid_request_error"
}{
"message": "authentication Failed",
"code": "request_failed",
"type": "authentication_error"
}{
"message": "Too many requests from IP. Check headers",
"code": "request_failed",
"type": "rate_limit_error"
}{
"message": "internal Server Error",
"code": "internal_error",
"type": "api_error"
}Bill Fetch
Bill Fetch Request
Use this API to initiate a bill fetch or bill validation request for a customer.
This is an async API. It returns only an acknowledgement with a ref_id.
The actual bill details must be retrieved separately by polling the Bill Fetch Response API using this ref_id.
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-api-version: <x-api-version>' \
--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": "INT",
"ip": "124.170.23.22",
"mobile": "9830098300",
"geo_code": "12.9667,77.5667",
"postal_code": "400063"
},
"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": "INT",
"ip": "124.170.23.22",
"mobile": "9830098300",
"geo_code": "12.9667,77.5667",
"postal_code": "400063"
},
"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-api-version": "<x-api-version>",
"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-api-version': '<x-api-version>',
'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: 'INT',
ip: '124.170.23.22',
mobile: '9830098300',
geo_code: '12.9667,77.5667',
postal_code: '400063'
},
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' => 'INT',
'ip' => '124.170.23.22',
'mobile' => '9830098300',
'geo_code' => '12.9667,77.5667',
'postal_code' => '400063'
],
'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-api-version: <x-api-version>",
"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\": \"INT\",\n \"ip\": \"124.170.23.22\",\n \"mobile\": \"9830098300\",\n \"geo_code\": \"12.9667,77.5667\",\n \"postal_code\": \"400063\"\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-api-version", "<x-api-version>")
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-api-version", "<x-api-version>")
.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\": \"INT\",\n \"ip\": \"124.170.23.22\",\n \"mobile\": \"9830098300\",\n \"geo_code\": \"12.9667,77.5667\",\n \"postal_code\": \"400063\"\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-api-version"] = '<x-api-version>'
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\": \"INT\",\n \"ip\": \"124.170.23.22\",\n \"mobile\": \"9830098300\",\n \"geo_code\": \"12.9667,77.5667\",\n \"postal_code\": \"400063\"\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": "ACCEPTED",
"message": "Bill fetch request accepted for processing",
"data": {
"ref_id": "HENSVVR4QOS7X1UGPY7JGUV444P10102202",
"status": "PROCESSING",
"flow": "FETCH_AND_PAY"
}
}{
"message": "bill_fetch_request.agent_id : is missing in the request. Value received: ",
"code": "bill_fetch_request.agent_id_missing",
"type": "invalid_request_error"
}{
"message": "authentication Failed",
"code": "request_failed",
"type": "authentication_error"
}{
"message": "Too many requests from IP. Check headers",
"code": "request_failed",
"type": "rate_limit_error"
}{
"message": "internal Server Error",
"code": "internal_error",
"type": "api_error"
}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.
Body
application/json
Request parameters to initiate a bill fetch or bill validation request.
Show child attributes
Show child attributes
Response
Success response for initiating a bill fetch or bill validation request.
Always "ACCEPTED" when the request is successfully queued.
Example:
"ACCEPTED"
Human-readable confirmation that the request has been accepted for async processing.
Example:
"Bill fetch request accepted for processing"
Acknowledgement data returned immediately upon request acceptance.
Show child attributes
Show child attributes
Was this page helpful?
⌘I