Fetch Agent Institution Wallet Ledger
curl --request POST \
--url https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger \
--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 '
{
"start_date_time": "2025-01-01 00:00:00",
"end_date_time": "2025-01-31 23:59:59",
"sale_type": "DEBIT",
"utr": "UTR123456789"
}
'import requests
url = "https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger"
payload = {
"start_date_time": "2025-01-01 00:00:00",
"end_date_time": "2025-01-31 23:59:59",
"sale_type": "DEBIT",
"utr": "UTR123456789"
}
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({
start_date_time: '2025-01-01 00:00:00',
end_date_time: '2025-01-31 23:59:59',
sale_type: 'DEBIT',
utr: 'UTR123456789'
})
};
fetch('https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger', 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/agent/{agentId}/wallet/ledger",
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([
'start_date_time' => '2025-01-01 00:00:00',
'end_date_time' => '2025-01-31 23:59:59',
'sale_type' => 'DEBIT',
'utr' => 'UTR123456789'
]),
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/agent/{agentId}/wallet/ledger"
payload := strings.NewReader("{\n \"start_date_time\": \"2025-01-01 00:00:00\",\n \"end_date_time\": \"2025-01-31 23:59:59\",\n \"sale_type\": \"DEBIT\",\n \"utr\": \"UTR123456789\"\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/agent/{agentId}/wallet/ledger")
.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 \"start_date_time\": \"2025-01-01 00:00:00\",\n \"end_date_time\": \"2025-01-31 23:59:59\",\n \"sale_type\": \"DEBIT\",\n \"utr\": \"UTR123456789\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger")
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 \"start_date_time\": \"2025-01-01 00:00:00\",\n \"end_date_time\": \"2025-01-31 23:59:59\",\n \"sale_type\": \"DEBIT\",\n \"utr\": \"UTR123456789\"\n}"
response = http.request(request)
puts response.read_body{
"content": [
{
"id": 1001,
"wallet_id": 42,
"event": "BILL_PAYMENT_DEBIT",
"event_id": "CH0162455XTQK9MIPNYZ",
"sale_type": "DEBIT",
"amount": 250,
"closing_balance": 4750,
"utr": "UTR123456789",
"added_on": "2025-01-15 10:30:00",
"updated_on": "2025-01-15 10:30:05"
}
],
"size": 20,
"page": 0,
"last": true
}{
"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"
}Wallet
Fetch Agent Institution Wallet Ledger
Use this API to fetch a paginated list of wallet ledger entries for a given Agent Institution. Includes credits (recharges) and debits (bill payments). Results can be filtered by date range, transaction type, or UTR. All request body fields are optional. An empty body returns all entries.
The ledger lists wallet credits (recharges) and debits (bill payments). On the prefunding model, each bill payment also produces freeze and unfreeze hold entries against the prefunded balance. On the shortfall (postfunding) model, debits can take the running balance negative, reflecting the amount drawn against the credit line.
POST
/
bbps
/
cou
/
agent
/
{agentId}
/
wallet
/
ledger
Fetch Agent Institution Wallet Ledger
curl --request POST \
--url https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger \
--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 '
{
"start_date_time": "2025-01-01 00:00:00",
"end_date_time": "2025-01-31 23:59:59",
"sale_type": "DEBIT",
"utr": "UTR123456789"
}
'import requests
url = "https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger"
payload = {
"start_date_time": "2025-01-01 00:00:00",
"end_date_time": "2025-01-31 23:59:59",
"sale_type": "DEBIT",
"utr": "UTR123456789"
}
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({
start_date_time: '2025-01-01 00:00:00',
end_date_time: '2025-01-31 23:59:59',
sale_type: 'DEBIT',
utr: 'UTR123456789'
})
};
fetch('https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger', 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/agent/{agentId}/wallet/ledger",
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([
'start_date_time' => '2025-01-01 00:00:00',
'end_date_time' => '2025-01-31 23:59:59',
'sale_type' => 'DEBIT',
'utr' => 'UTR123456789'
]),
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/agent/{agentId}/wallet/ledger"
payload := strings.NewReader("{\n \"start_date_time\": \"2025-01-01 00:00:00\",\n \"end_date_time\": \"2025-01-31 23:59:59\",\n \"sale_type\": \"DEBIT\",\n \"utr\": \"UTR123456789\"\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/agent/{agentId}/wallet/ledger")
.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 \"start_date_time\": \"2025-01-01 00:00:00\",\n \"end_date_time\": \"2025-01-31 23:59:59\",\n \"sale_type\": \"DEBIT\",\n \"utr\": \"UTR123456789\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.cashfree.com/bbps/cou/agent/{agentId}/wallet/ledger")
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 \"start_date_time\": \"2025-01-01 00:00:00\",\n \"end_date_time\": \"2025-01-31 23:59:59\",\n \"sale_type\": \"DEBIT\",\n \"utr\": \"UTR123456789\"\n}"
response = http.request(request)
puts response.read_body{
"content": [
{
"id": 1001,
"wallet_id": 42,
"event": "BILL_PAYMENT_DEBIT",
"event_id": "CH0162455XTQK9MIPNYZ",
"sale_type": "DEBIT",
"amount": 250,
"closing_balance": 4750,
"utr": "UTR123456789",
"added_on": "2025-01-15 10:30:00",
"updated_on": "2025-01-15 10:30:05"
}
],
"size": 20,
"page": 0,
"last": true
}{
"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.
Path Parameters
The Agent Institution ID (bbpsAgentInstituteId) that owns the wallet. This is the parent institution identifier, not the channel-specific agent_id used in the Bill Fetch and Bill Payment APIs.
Query Parameters
Zero-indexed page number. Default is 0.
Number of entries per page. Default is 20.
Body
application/json
Request parameters to filter wallet ledger entries.
Filter entries from this datetime. Format: yyyy-MM-dd HH:mm:ss.
Example:
"2025-01-01 00:00:00"
Filter entries up to this datetime. Format: yyyy-MM-dd HH:mm:ss.
Example:
"2025-01-31 23:59:59"
Filter by transaction type.
Available options:
CREDIT, DEBIT Example:
"DEBIT"
Filter by Unique Transaction Reference number.
Example:
"UTR123456789"
Response
Success response for fetching a paginated list of wallet ledger entries for a given Agent Institution.
Was this page helpful?