Refunds
This page will help you understand the refund workflow with Cashfree APIs.
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"
}
Updated 9 months ago