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"
}

Did this page help you?