Create Refund Endpoint | Cashfree Payments

Create Refund

curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/{order_id}/refunds \
  --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_amount": 1,
  "refund_id": "refund_00912",
  "refund_note": "refund note for reference",
  "refund_speed": "STANDARD"
}
'

import requests

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

payload = {
    "refund_amount": 1,
    "refund_id": "refund_00912",
    "refund_note": "refund note for reference",
    "refund_speed": "STANDARD"
}
headers = {
    "x-api-version": "<x-api-version>",
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  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_amount: 1,
    refund_id: 'refund_00912',
    refund_note: 'refund note for reference',
    refund_speed: 'STANDARD'
  })
};

fetch('https://sandbox.cashfree.com/pg/orders/{order_id}/refunds', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'refund_amount' => 1,
    'refund_id' => 'refund_00912',
    'refund_note' => 'refund note for reference',
    'refund_speed' => 'STANDARD'
  ]),
  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"

	payload := strings.NewReader("{\n  \"refund_amount\": 1,\n  \"refund_id\": \"refund_00912\",\n  \"refund_note\": \"refund note for reference\",\n  \"refund_speed\": \"STANDARD\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://sandbox.cashfree.com/pg/orders/{order_id}/refunds")
  .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_amount\": 1,\n  \"refund_id\": \"refund_00912\",\n  \"refund_note\": \"refund note for reference\",\n  \"refund_speed\": \"STANDARD\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.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_amount\": 1,\n  \"refund_id\": \"refund_00912\",\n  \"refund_note\": \"refund note for reference\",\n  \"refund_speed\": \"STANDARD\"\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": "SUCCESS",
    "refund_type": "MERCHANT_INITIATED",
    "refund_splits": [],
    "status_description": "In Progress",
    "refund_arn": "RF12312",
    "metadata": null,
    "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"
}

POST

orders

{order_id}

refunds

Create Refund

curl --request POST \
  --url https://sandbox.cashfree.com/pg/orders/{order_id}/refunds \
  --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_amount": 1,
  "refund_id": "refund_00912",
  "refund_note": "refund note for reference",
  "refund_speed": "STANDARD"
}
'

import requests

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

payload = {
    "refund_amount": 1,
    "refund_id": "refund_00912",
    "refund_note": "refund note for reference",
    "refund_speed": "STANDARD"
}
headers = {
    "x-api-version": "<x-api-version>",
    "x-client-id": "<api-key>",
    "x-client-secret": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  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_amount: 1,
    refund_id: 'refund_00912',
    refund_note: 'refund note for reference',
    refund_speed: 'STANDARD'
  })
};

fetch('https://sandbox.cashfree.com/pg/orders/{order_id}/refunds', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'refund_amount' => 1,
    'refund_id' => 'refund_00912',
    'refund_note' => 'refund note for reference',
    'refund_speed' => 'STANDARD'
  ]),
  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"

	payload := strings.NewReader("{\n  \"refund_amount\": 1,\n  \"refund_id\": \"refund_00912\",\n  \"refund_note\": \"refund note for reference\",\n  \"refund_speed\": \"STANDARD\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://sandbox.cashfree.com/pg/orders/{order_id}/refunds")
  .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_amount\": 1,\n  \"refund_id\": \"refund_00912\",\n  \"refund_note\": \"refund note for reference\",\n  \"refund_speed\": \"STANDARD\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.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_amount\": 1,\n  \"refund_id\": \"refund_00912\",\n  \"refund_note\": \"refund note for reference\",\n  \"refund_speed\": \"STANDARD\"\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": "SUCCESS",
    "refund_type": "MERCHANT_INITIATED",
    "refund_splits": [],
    "status_description": "In Progress",
    "refund_arn": "RF12312",
    "metadata": null,
    "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"
}

Run in Postman: You can also try this API in our Postman Collection.

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.

Body

application/json

Request parameters to initiate refunds.

refund_amount

number<double>

required

Amount to be refunded. Should be lesser than or equal to the transaction amount. (Decimals allowed).

refund_id

string

required

An unique ID to associate the refund with. Provie alphanumeric values.

Required string length: 3 - 40

refund_note

string

A refund note for your reference. To simulate refund status in Sandbox, pass SUCCESS, FAILED, PENDING, or ACTIVE in the refund_note field. This is a case-sensitive parameter.

Required string length: 3 - 100

refund_speed

enum<string>

Speed at which the refund is processed. It's an optional field with default being STANDARD.

Available options:

STANDARD,

INSTANT

refund_splits

object[]

Show child attributes

Response

Success response for initiating 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.

Webhooks Get Refund

⌘I

Payments API

v2026-01-01

Other Versions

Create Refund

Authorizations

Headers

Path Parameters

Body

Response