Skip to main content
POST
/
ppi
/
wallet
/
refund
Wallet Debit Refund
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"
  }
}
'
{
  "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
  },
  "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

The following table outlines the possible status values returned in the refund response:
StatusDescription
SUCCESSThe refund has been processed successfully and the amount has been credited back to the user’s sub-wallet. The transaction is complete.
PENDINGThe 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

​
x-client-id
string
header
required

Your unique client identifier issued by Cashfree.

​
x-client-secret
string
header
required

The secret key associated with your client ID.

Headers

​
x-api-version
string
default:2025-11-01
required

API version to be used. Format is in YYYY-MM-DD.

Example:

"2025-11-01"

Body

application/json
​
refund_id
string
required

Unique identifier that you create to identify the refund transaction in your system. Maximum 50 characters. Only alphanumeric characters, periods (.), hyphens (-), and underscores (_) are allowed.

Required string length: 1 - 50
Example:

"REFUND420984"

​
debit_id
string
required

Unique identifier of the original debit transaction for which the refund is being initiated.

Required string length: 1 - 50
Example:

"DEBIT1244"

​
user_id
string
required

Unique identifier for the user, as provided by you during PPI user creation.

Required string length: 1 - 50
Example:

"USER827364"

​
wallet_id
string
required

Unique identifier for the wallet, as provided by you during wallet creation.

Required string length: 1 - 50
Example:

"WALLET936721"

​
cf_sub_wallet_id
string
required

Unique identifier of the sub-wallet from which the original debit was made and to which the refund will be credited.

Required string length: 1 - 50
Example:

"35246543210987654321"

​
amount
number<double>
required

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.01
Example:

100.5

​
remarks
string

Additional remarks for the refund request. Alphanumeric and whitespaces are allowed. The maximum character limit is 500.

Maximum string length: 500
Example:

"Wallet Refund"

​
notes
object

Additional key-value pairs for any extra information you want to store for this refund transaction. This is optional.

Example:
{
  "example_key1": "example_value1",
  "example_key2": "example_value2"
}

Response

Wallet refund request processed successfully.

​
refund_id
string

Unique identifier for the refund transaction, as provided by you during the refund request.

Example:

"REFUND420984"

​
debit_id
string

Unique identifier of the original debit transaction for which this refund was initiated.

Example:

"DEBIT1244"

​
cf_refund_id
string

Unique identifier for the refund transaction, generated by Cashfree.

Example:

"8901234567890123456"

​
user_id
string

Unique identifier for the user, as provided by you during PPI user creation.

Example:

"USER827364"

​
wallet_id
string

Primary wallet ID to which the refund amount has been credited.

Example:

"WALLET936721"

​
sub_wallet
object

Sub-wallet details to which the refund amount has been credited.

​
status
enum<string>

Status of the refund operation:

  • SUCCESS: Refund has been processed successfully and amount credited to wallet
  • PENDING: Refund is being processed and will be credited shortly
Available options:
SUCCESS,
PENDING
Example:

"SUCCESS"

​
refunded_gift_codes
object[]

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.

​
amount
number<double>

Amount that was refunded to the wallet.

Example:

100.5

​
remarks
string

Remarks for the refund transaction.

Example:

"Wallet Refund"

​
notes
object

key-value pairs of any extra information shared during refund transaction.

Example:
{
  "example_key1": "example_value1",
  "example_key2": "example_value2"
}
​
initiated_at
string<date-time>

Timestamp when the refund transaction was initiated.

Example:

"2025-07-28T10:30:00Z"

​
processed_at
string<date-time> | null

Timestamp when the refund transaction was processed. Will be null if status is PENDING.

Example:

"2025-07-28T10:30:00Z"