Cashfree Payments Developer Documentation

Update Refund

curl --request PUT \
  --url https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id} \
  --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_status": "CANCELLED",
  "remarks": "Requesting cancellation of refund"
}
'

import requests

url = "https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}"

payload = {
    "refund_status": "CANCELLED",
    "remarks": "Requesting cancellation of refund"
}
headers = {
    "x-api-version": "<x-api-version>",
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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_status: 'CANCELLED', remarks: 'Requesting cancellation of refund'})
};

fetch('https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}', 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://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'refund_status' => 'CANCELLED',
    'remarks' => 'Requesting cancellation of refund'
  ]),
  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://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}"

	payload := strings.NewReader("{\n  \"refund_status\": \"CANCELLED\",\n  \"remarks\": \"Requesting cancellation of refund\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}")
  .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_status\": \"CANCELLED\",\n  \"remarks\": \"Requesting cancellation of refund\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.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_status\": \"CANCELLED\",\n  \"remarks\": \"Requesting cancellation of refund\"\n}"

response = http.request(request)
puts response.read_body

{
  "cf_payment_id": "918812",
  "cf_refund_id": "1553338",
  "refund_id": "REF-123",
  "order_id": "c6G-QMcbm1848",
  "entity": "refund",
  "refund_amount": 100.81,
  "refund_currency": "INR",
  "refund_note": "Refund for order #123",
  "refund_status": "CANCELLED",
  "refund_type": "MERCHANT_INITIATED",
  "refund_splits": [],
  "status_description": "Refund is cancelled",
  "refund_speed": {
    "requested": "INSTANT,",
    "accepted": "INSTANT,",
    "processed": "null,",
    "message": null
  },
  "refund_arn": "RF12312",
  "metadata": {
    "key1": "myValue"
  },
  "created_at": "2021-07-25T08:57:52+05:30",
  "processed_at": "2021-07-25T12:57:52+05:30",
  "refund_charge": 0,
  "refund_mode": "STANDARD",
  "forex_conversion_handling_charge": 11.12,
  "forex_conversion_handling_tax": 1.12,
  "forex_conversion_rate": 84.24,
  "charges_currency": "INR"
}

{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "something_not_found",
  "type": "invalid_request_error"
}

{
  "message": "order with same id is already present",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "order_already_exists",
  "type": "invalid_request_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_invalid",
  "type": "idempotency_error"
}

{
  "message": "Too many requests from IP. Check headers",
  "code": "request_failed",
  "type": "rate_limit_error"
}

{
  "message": "internal Server Error",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "internal_error",
  "type": "api_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "bank_processing_failure",
  "type": "api_error"
}

PUT

orders

{order_id}

refunds

{refund_id}

Update Refund

curl --request PUT \
  --url https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id} \
  --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_status": "CANCELLED",
  "remarks": "Requesting cancellation of refund"
}
'

import requests

url = "https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}"

payload = {
    "refund_status": "CANCELLED",
    "remarks": "Requesting cancellation of refund"
}
headers = {
    "x-api-version": "<x-api-version>",
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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_status: 'CANCELLED', remarks: 'Requesting cancellation of refund'})
};

fetch('https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}', 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://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'refund_status' => 'CANCELLED',
    'remarks' => 'Requesting cancellation of refund'
  ]),
  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://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}"

	payload := strings.NewReader("{\n  \"refund_status\": \"CANCELLED\",\n  \"remarks\": \"Requesting cancellation of refund\"\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}")
  .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_status\": \"CANCELLED\",\n  \"remarks\": \"Requesting cancellation of refund\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.cashfree.com/pg/orders/{order_id}/refunds/{refund_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.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_status\": \"CANCELLED\",\n  \"remarks\": \"Requesting cancellation of refund\"\n}"

response = http.request(request)
puts response.read_body

{
  "cf_payment_id": "918812",
  "cf_refund_id": "1553338",
  "refund_id": "REF-123",
  "order_id": "c6G-QMcbm1848",
  "entity": "refund",
  "refund_amount": 100.81,
  "refund_currency": "INR",
  "refund_note": "Refund for order #123",
  "refund_status": "CANCELLED",
  "refund_type": "MERCHANT_INITIATED",
  "refund_splits": [],
  "status_description": "Refund is cancelled",
  "refund_speed": {
    "requested": "INSTANT,",
    "accepted": "INSTANT,",
    "processed": "null,",
    "message": null
  },
  "refund_arn": "RF12312",
  "metadata": {
    "key1": "myValue"
  },
  "created_at": "2021-07-25T08:57:52+05:30",
  "processed_at": "2021-07-25T12:57:52+05:30",
  "refund_charge": 0,
  "refund_mode": "STANDARD",
  "forex_conversion_handling_charge": 11.12,
  "forex_conversion_handling_tax": 1.12,
  "forex_conversion_rate": 84.24,
  "charges_currency": "INR"
}

{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "something_not_found",
  "type": "invalid_request_error"
}

{
  "message": "order with same id is already present",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "order_already_exists",
  "type": "invalid_request_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_invalid",
  "type": "idempotency_error"
}

{
  "message": "Too many requests from IP. Check headers",
  "code": "request_failed",
  "type": "rate_limit_error"
}

{
  "message": "internal Server Error",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "internal_error",
  "type": "api_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "bank_processing_failure",
  "type": "api_error"
}

Authorizations

x-client-id

string

header

required

Client app ID. You can find your app id in the Merchant Dashboard.

x-client-secret

string

header

required

Client secret key. You can find your secret key in the Merchant Dashboard.

Headers

x-api-version

string

default:2025-01-01

required

API version to be used.

x-request-id

string

Request ID for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to Cashfree.

x-idempotency-key

string<UUID>

An idempotency key is a unique identifier you include with your API call. If the request fails or times out, you can safely retry it using the same key to avoid duplicate actions.

Path Parameters

order_id

string

required

The ID which uniquely identifies your order.

refund_id

string

required

Refund Id of the refund you want to update.

Body

application/json

Request parameters to update refund details.

refund_status

enum<string>

required

Allowed values: ["CANCELLED"].

Available options:

CANCELLED

remarks

string

Add remarks for your reference.

Maximum string length: 250

Response

Success response for updating refunds.

cf_payment_id

string

Cashfree Payments ID of the payment for which refund is initiated.

cf_refund_id

string

Cashfree Payments ID for a refund.

order_id

string

Merchant’s order Id of the order for which refund is initiated.

refund_id

string

Merchant’s refund ID of the refund.

entity

enum<string>

Type of object.

Available options:

refund

refund_amount

number

Amount that is refunded.

refund_currency

string

Currency of the refund amount.

refund_note

string

Note added by merchant for the refund.

refund_status

enum<string>

This can be one of ["SUCCESS", "PENDING", "CANCELLED", "ONHOLD", "FAILED"].

Available options:

SUCCESS,

PENDING,

CANCELLED,

ONHOLD

refund_arn

string

The bank reference number for refund.

refund_charge

number

Charges in INR for processing refund.

status_description

string

Description of refund status.

metadata

object

Key-value pair that can be used to store additional information about the entity. Maximum 5 key-value pairs.

refund_splits

VendorSplit · object[]

Show child attributes

refund_type

enum<string>

This can be one of ["PAYMENT_AUTO_REFUND", "MERCHANT_INITIATED", "UNRECONCILED_AUTO_REFUND"].

Available options:

PAYMENT_AUTO_REFUND,

MERCHANT_INITIATED,

UNRECONCILED_AUTO_REFUND

refund_mode

string

Method or speed of processing refund.

created_at

string

Time of refund creation.

processed_at

string

Time when refund was processed successfully.

refund_speed

RefundSpeed · object

How fast refund has to be proecessed.

Show child attributes

Example:

{
  "requested": "STANDARD",
  "accepted": "STANDARD",
  "processed": "STANDARD",
  "message": "Error message, if any"
}

forex_conversion_handling_charge

number

Cashfree forex conversion charges for refund processing.

forex_conversion_handling_tax

number

Cashfree forex conversion tax for refund processing.

forex_conversion_rate

number

Cashfree forex conversion rate for refund processing.

charges_currency

string

Cashfree refund charges currency for a refund.

Get All Refunds for an Order Webhooks

⌘I

Payments API

v2026-01-01

Other Versions

Update Refund

Authorizations

Headers

Path Parameters

Body

Response