Refunds

Refunds are payments returned back to the customer either fully or partially by the merchant. Merchants can initiate refunds for a payment processed earlier through Cashfree Payments for various reasons like order cancellation by customer, lack of available inventory with merchant, etc

Create Refund

Refunds can be created via either APIs or through Merchant Dashboard.

Create Refund via API

curl --request POST \
     --url https://sandbox.cashfree.com/pg/orders/k0v-vK1jv34/refunds \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-version: 2022-01-01' \
     --header 'x-client-id: <client_id>' \
     --header 'x-client-secret: <client_secret>' \
     --data '
{
     "refund_amount": 1,
     "refund_id": "refund_009126",
     "refund_note": "refund for order k0v-vK1jv34"
}
'

{
   "cf_payment_id":1296177,
   "cf_refund_id":"refund_33056",
   "created_at":"2022-02-02T09:45:24+05:30",
   "entity":"refund",
   "metadata":null,
   "order_id":"k0v-vK1jv34",
   "processed_at":null,
   "refund_amount":1.00,
   "refund_arn":null,
   "refund_charge":0.00,
   "refund_currency":"INR",
   "refund_id":"refund_009126",
   "refund_note":"refund note for reference",
   "refund_splits":[],
   "refund_status":"PENDING",
   "refund_mode":"STANDARD",
   "refund_type":"MERCHANT_INITIATED",
   "status_description":"In Progress"
}

Payload Field Description

Field	Description	Example
cf_refund_id	Cashfree Payments ID for a refund	11325632
cf_payment_id	Cashfree Payments ID of the payment for which refund is initiated	789727431
refund_id	Merchant’s refund ID of the refund	refund_sampleorder0413
order_id	Merchant’s order Id of the order for which refund is initiated	sampleorder0413
refund_amount	Amount that was refunded	2.00
refund_currency	Currency of the refund amount	INR
entity	Type of object (refund always)	refund
refund_type	Type of refund (One of MERCHANT_INITIATED, PAYMENT_AUTO_REFUND, UNRECONCILED_AUTO_REFUND)	MERCHANT_INITIATED
refund_arn	The bank reference number for refund	205907014017
refund_status	Status of the refund (One of SUCCESS, CANCELLED, PENDING, ONHOLD)	PENDING
status_description	Complete description of the refund status	In Progress
created_at	Time of refund creation	2022-02-28T12:54:25+05:30
processed_at	Time when refund was processed successfully	2022-02-28T13:04:27+05:30
refund_charge	Charges in INR for processing refund	0
refund_note	Note added by merchant for the refund	Cancelled Order
refund_splits	Refund split details	[]
metadata	Additional refund metadata	null
refund_mode	Method or speed of processing refund (INSTANT or STANDARD)	STANDARD

refund_status

List of possible refund status along with a generic description

Value	Description
PENDING	The refund request is accepted by Cashfree Payments buy yet to be accepted by the respective banks
SUCCESS	The refund request is successfully accepted by the bank and the payment would get credited to the customer in 3-4 days
ONHOLD	The refund request is kept on hold because the merchant has insufficient balance in their Cashfree Payments account
CANCELLED	The refund request which was earlier accepted by Cashfree Payments is cancelled because it could not be processed by the Bank

status_description

List of detailed status descriptions for various refund status

refund_status	status_description
PENDING	In Progress
PENDING	Refund request sent to bank for processing refund manually
PENDING	Refund request is getting processed via payouts
PENDING	Request sent to merchant to collect customer details
SUCCESS	Refund processed successfully
CANCELLED	Refund is cancelled
ONHOLD	Refund on hold because of insufficient account balance

refund_type

Value	Description
MERCHANT_INITIATED	The refund was initiated on the request of merchant
PAYMENT_AUTO_REFUND	The refund was initiated because Cashfree Payments could not return a success response for payment within an agreed timeline, or if the customer had raised dispute for the order with Cashfree
UNRECONCILED_AUTO_REFUND	If the payment was done to a merchant but could not be reconciled with any of the merchant orders, then the payment is auto refunded to the customer

Get all refunds for an order

To query all the refunds associated with an order

curl --request GET \
     --url https://api.cashfree.com/pg/orders/k0v-vK1jv34/refunds \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-version: 2022-01-01' \
     --header 'x-client-id: <client_id>' \
     --header 'x-client-secret: <secret_key>'

[
   {
      "cf_payment_id":741131079,
      "cf_refund_id":"refund_10734136",
      "created_at":"2022-02-03T12:31:41+05:30",
      "entity":"refund",
      "metadata":null,
      "order_id":"k0v-vK1jv34",
      "processed_at":"2022-02-03T12:41:45+05:30",
      "refund_amount":1.00,
      "refund_arn":"6438723048736130406146",
      "refund_charge":0.00,
      "refund_currency":"INR",
      "refund_id":"refund_009126",
      "refund_mode":"STANDARD",
      "refund_note":"refund note for reference",
      "refund_splits":[],
      "refund_status":"SUCCESS",
      "refund_type":"MERCHANT_INITIATED",
      "status_description":"Refund processed successfully"
   }
]

Get a single refund for an order

To query a particular refund for an order

curl --request GET \
     --url https://api.cashfree.com/pg/orders/k0v-vK1jv34/refunds/refund_009126 \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-version: 2022-01-01' \
     --header 'x-client-id: 1848d0ce8441fb8ffa258bc98481' \
     --header 'x-client-secret: f7cbcd7ba238c4f85a4083c39f9386be33de1214'

{
   "cf_payment_id":741131079,
   "cf_refund_id":"refund_10734136",
   "created_at":"2022-02-03T12:31:41+05:30",
   "entity":"refund",
   "metadata":null,
   "order_id":"k0v-vK1jv34",
   "processed_at":"2022-02-03T12:41:45+05:30",
   "refund_amount":1.00,
   "refund_arn":"6438723048736130406146",
   "refund_charge":0.00,
   "refund_currency":"INR",
   "refund_id":"refund_009126",
   "refund_mode":"STANDARD",
   "refund_note":"refund note for reference",
   "refund_splits":[],
   "refund_status":"SUCCESS",
   "refund_type":"MERCHANT_INITIATED",
   "status_description":"Refund processed successfully"
}