Refund Debit Wallet
curl --request POST \
--url https://api.cashfree.com/ppi/wallet/refund \
--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 '
{
"refund_id": "REFUND420984",
"debit_id": "DEBIT1244",
"user_id": "USER827364",
"wallet_id": "WALLET936721",
"cf_sub_wallet_id": "35246543210987654321",
"amount": 100.5,
"remarks": "Wallet Refund",
"notes": {
"example_key1": "example_value1",
"example_key2": "example_value2"
}
}
'import requests
url = "https://api.cashfree.com/ppi/wallet/refund"
payload = {
"refund_id": "REFUND420984",
"debit_id": "DEBIT1244",
"user_id": "USER827364",
"wallet_id": "WALLET936721",
"cf_sub_wallet_id": "35246543210987654321",
"amount": 100.5,
"remarks": "Wallet Refund",
"notes": {
"example_key1": "example_value1",
"example_key2": "example_value2"
}
}
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({
refund_id: 'REFUND420984',
debit_id: 'DEBIT1244',
user_id: 'USER827364',
wallet_id: 'WALLET936721',
cf_sub_wallet_id: '35246543210987654321',
amount: 100.5,
remarks: 'Wallet Refund',
notes: {example_key1: 'example_value1', example_key2: 'example_value2'}
})
};
fetch('https://api.cashfree.com/ppi/wallet/refund', 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://api.cashfree.com/ppi/wallet/refund",
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([
'refund_id' => 'REFUND420984',
'debit_id' => 'DEBIT1244',
'user_id' => 'USER827364',
'wallet_id' => 'WALLET936721',
'cf_sub_wallet_id' => '35246543210987654321',
'amount' => 100.5,
'remarks' => 'Wallet Refund',
'notes' => [
'example_key1' => 'example_value1',
'example_key2' => 'example_value2'
]
]),
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://api.cashfree.com/ppi/wallet/refund"
payload := strings.NewReader("{\n \"refund_id\": \"REFUND420984\",\n \"debit_id\": \"DEBIT1244\",\n \"user_id\": \"USER827364\",\n \"wallet_id\": \"WALLET936721\",\n \"cf_sub_wallet_id\": \"35246543210987654321\",\n \"amount\": 100.5,\n \"remarks\": \"Wallet Refund\",\n \"notes\": {\n \"example_key1\": \"example_value1\",\n \"example_key2\": \"example_value2\"\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://api.cashfree.com/ppi/wallet/refund")
.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 \"refund_id\": \"REFUND420984\",\n \"debit_id\": \"DEBIT1244\",\n \"user_id\": \"USER827364\",\n \"wallet_id\": \"WALLET936721\",\n \"cf_sub_wallet_id\": \"35246543210987654321\",\n \"amount\": 100.5,\n \"remarks\": \"Wallet Refund\",\n \"notes\": {\n \"example_key1\": \"example_value1\",\n \"example_key2\": \"example_value2\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cashfree.com/ppi/wallet/refund")
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 \"refund_id\": \"REFUND420984\",\n \"debit_id\": \"DEBIT1244\",\n \"user_id\": \"USER827364\",\n \"wallet_id\": \"WALLET936721\",\n \"cf_sub_wallet_id\": \"35246543210987654321\",\n \"amount\": 100.5,\n \"remarks\": \"Wallet Refund\",\n \"notes\": {\n \"example_key1\": \"example_value1\",\n \"example_key2\": \"example_value2\"\n }\n}"
response = http.request(request)
puts response.read_body{
"refund_id": "REFUND420984",
"debit_id": "DEBIT1244",
"cf_refund_id": "8901234567890123456",
"user_id": "USER827364",
"wallet_id": "WALLET936721",
"sub_wallet": {
"cf_sub_wallet_id": "35246543210987654321",
"name": "Gift Wallet",
"type": "GIFT_PPI",
"status": "ACTIVE",
"balance": 1500.75,
"available_balance": 1500.75,
"funds_on_hold": 0
},
"status": "SUCCESS",
"refunded_gift_codes": [
{
"code": "GHO-8900-HKDH-8899",
"amount_refunded": 50,
"value": 150,
"expiry": "2026-07-28T10:30:00Z"
},
{
"code": "ABC-1234-WXYZ-5678",
"amount_refunded": 50.5,
"value": 200.5,
"expiry": "2026-12-31T23:59:59Z"
}
],
"amount": 100.5,
"remarks": "Wallet Refund",
"notes": {
"example_key1": "example_value1",
"example_key2": "example_value2"
},
"initiated_at": "2025-07-28T10:30:00Z",
"processed_at": "2025-07-28T10:30:00Z"
}Wallets
Refund Debit Wallet
Processes a refund for a previously debited transaction from a user’s sub-wallet. The refund operation credits the amount back to the user’s sub-wallet, effectively reversing a debit transaction:
GIFT_PPI: Credits amount back to gift wallet.CLOSED_LOOP_PPI: Credits amount back to the respective sub-wallet.STANDARD_PPI: Credits amount back to the respective sub-wallet.- Refund amount cannot exceed the original debit amount.
POST
/
ppi
/
wallet
/
refund
Refund Debit Wallet
curl --request POST \
--url https://api.cashfree.com/ppi/wallet/refund \
--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 '
{
"refund_id": "REFUND420984",
"debit_id": "DEBIT1244",
"user_id": "USER827364",
"wallet_id": "WALLET936721",
"cf_sub_wallet_id": "35246543210987654321",
"amount": 100.5,
"remarks": "Wallet Refund",
"notes": {
"example_key1": "example_value1",
"example_key2": "example_value2"
}
}
'import requests
url = "https://api.cashfree.com/ppi/wallet/refund"
payload = {
"refund_id": "REFUND420984",
"debit_id": "DEBIT1244",
"user_id": "USER827364",
"wallet_id": "WALLET936721",
"cf_sub_wallet_id": "35246543210987654321",
"amount": 100.5,
"remarks": "Wallet Refund",
"notes": {
"example_key1": "example_value1",
"example_key2": "example_value2"
}
}
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({
refund_id: 'REFUND420984',
debit_id: 'DEBIT1244',
user_id: 'USER827364',
wallet_id: 'WALLET936721',
cf_sub_wallet_id: '35246543210987654321',
amount: 100.5,
remarks: 'Wallet Refund',
notes: {example_key1: 'example_value1', example_key2: 'example_value2'}
})
};
fetch('https://api.cashfree.com/ppi/wallet/refund', 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://api.cashfree.com/ppi/wallet/refund",
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([
'refund_id' => 'REFUND420984',
'debit_id' => 'DEBIT1244',
'user_id' => 'USER827364',
'wallet_id' => 'WALLET936721',
'cf_sub_wallet_id' => '35246543210987654321',
'amount' => 100.5,
'remarks' => 'Wallet Refund',
'notes' => [
'example_key1' => 'example_value1',
'example_key2' => 'example_value2'
]
]),
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://api.cashfree.com/ppi/wallet/refund"
payload := strings.NewReader("{\n \"refund_id\": \"REFUND420984\",\n \"debit_id\": \"DEBIT1244\",\n \"user_id\": \"USER827364\",\n \"wallet_id\": \"WALLET936721\",\n \"cf_sub_wallet_id\": \"35246543210987654321\",\n \"amount\": 100.5,\n \"remarks\": \"Wallet Refund\",\n \"notes\": {\n \"example_key1\": \"example_value1\",\n \"example_key2\": \"example_value2\"\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://api.cashfree.com/ppi/wallet/refund")
.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 \"refund_id\": \"REFUND420984\",\n \"debit_id\": \"DEBIT1244\",\n \"user_id\": \"USER827364\",\n \"wallet_id\": \"WALLET936721\",\n \"cf_sub_wallet_id\": \"35246543210987654321\",\n \"amount\": 100.5,\n \"remarks\": \"Wallet Refund\",\n \"notes\": {\n \"example_key1\": \"example_value1\",\n \"example_key2\": \"example_value2\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cashfree.com/ppi/wallet/refund")
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 \"refund_id\": \"REFUND420984\",\n \"debit_id\": \"DEBIT1244\",\n \"user_id\": \"USER827364\",\n \"wallet_id\": \"WALLET936721\",\n \"cf_sub_wallet_id\": \"35246543210987654321\",\n \"amount\": 100.5,\n \"remarks\": \"Wallet Refund\",\n \"notes\": {\n \"example_key1\": \"example_value1\",\n \"example_key2\": \"example_value2\"\n }\n}"
response = http.request(request)
puts response.read_body{
"refund_id": "REFUND420984",
"debit_id": "DEBIT1244",
"cf_refund_id": "8901234567890123456",
"user_id": "USER827364",
"wallet_id": "WALLET936721",
"sub_wallet": {
"cf_sub_wallet_id": "35246543210987654321",
"name": "Gift Wallet",
"type": "GIFT_PPI",
"status": "ACTIVE",
"balance": 1500.75,
"available_balance": 1500.75,
"funds_on_hold": 0
},
"status": "SUCCESS",
"refunded_gift_codes": [
{
"code": "GHO-8900-HKDH-8899",
"amount_refunded": 50,
"value": 150,
"expiry": "2026-07-28T10:30:00Z"
},
{
"code": "ABC-1234-WXYZ-5678",
"amount_refunded": 50.5,
"value": 200.5,
"expiry": "2026-12-31T23:59:59Z"
}
],
"amount": 100.5,
"remarks": "Wallet Refund",
"notes": {
"example_key1": "example_value1",
"example_key2": "example_value2"
},
"initiated_at": "2025-07-28T10:30:00Z",
"processed_at": "2025-07-28T10:30:00Z"
}Refund Status Descriptions
Refund Status Descriptions
The following table outlines the possible status values returned in the refund response:
| Status | Description |
|---|---|
SUCCESS | The refund has been processed successfully and the amount has been credited back to the user’s sub-wallet. The transaction is complete. |
PENDING | The refund request has been accepted and is currently being processed. The amount will be credited to the wallet shortly. Check the status later or wait for webhook notification. |
Authorizations
Your unique client identifier issued by Cashfree. You can find this in your Merchant Dashboard.
The secret key associated with your client ID. Use this to authenticate your API requests. You can find this in your Merchant Dashboard.
Headers
API version to be used. Format is in YYYY-MM-DD.
Example:
"2025-11-01"
Body
application/json
Request parameters to refund a previous debit transaction back to the user's wallet.
Unique identifier that you create to identify the refund transaction in your system. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed.
Required string length:
1 - 50Example:
"REFUND420984"
Unique identifier of the original debit transaction for which the refund is being initiated. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed.
Required string length:
1 - 50Example:
"DEBIT1244"
Unique identifier for the user, as provided by you during PPI user creation. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed.
Required string length:
1 - 50Example:
"USER827364"
Unique identifier for the wallet, as provided by you during wallet creation. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed.
Required string length:
1 - 50Example:
"WALLET936721"
Unique identifier of the sub-wallet from which the original debit was made and to which the refund will be credited. Only numeric characters are allowed.
Required string length:
1 - 19Example:
"35246543210987654321"
Amount to refund. Decimal values are allowed. The amount should be greater than 0 and cannot exceed the original debit amount or the remaining refundable amount.
Required range:
x >= 0.01Example:
100.5
Additional remarks for the refund request. Alphanumeric and whitespaces are allowed. The maximum character limit is 500.
Maximum string length:
500Example:
"Wallet Refund"
Optional key-value pairs for any extra information. Keys and values must be strings. The following constraints apply:
- Maximum 10 entries.
- Keys: maximum 50 characters. Alphanumeric characters, underscores (_), periods (.), commas (,), single quotes ('), ampersands (&), hyphens (-), and spaces are allowed.
- Values: maximum 200 characters. Same character set as keys.
Show child attributes
Show child attributes
Response
Success response for refunding a wallet debit.
Unique identifier for the refund transaction, as provided by you during the refund request.
Example:
"REFUND420984"
Unique identifier of the original debit transaction for which this refund was initiated.
Example:
"DEBIT1244"
Unique identifier for the refund transaction, generated by Cashfree.
Example:
"8901234567890123456"
Unique identifier for the user, as provided by you during PPI user creation.
Example:
"USER827364"
Primary wallet ID to which the refund amount has been credited.
Example:
"WALLET936721"
Show child attributes
Show child attributes
Status of the refund operation:
SUCCESS: Refund has been processed successfully and amount credited to walletPENDING: Refund is being processed and will be credited shortly
Available options:
SUCCESS, PENDING Example:
"SUCCESS"
List of gift codes that were refunded in the transaction. This is applicable only for GIFT_PPI type wallets and when the refund is successful.
Show child attributes
Show child attributes
Amount that was refunded to the wallet.
Example:
100.5
Remarks for the refund transaction.
Example:
"Wallet Refund"
Optional key-value pairs for any extra information. Keys and values must be strings. The following constraints apply:
- Maximum 10 entries.
- Keys: maximum 50 characters. Alphanumeric characters, underscores (_), periods (.), commas (,), single quotes ('), ampersands (&), hyphens (-), and spaces are allowed.
- Values: maximum 200 characters. Same character set as keys.
Show child attributes
Show child attributes
Timestamp when the refund transaction was initiated.
Example:
"2025-07-28T10:30:00Z"
Timestamp when the refund transaction was processed. Will be null if status is PENDING.
Example:
"2025-07-28T10:30:00Z"
Was this page helpful?