paymentservice/documentation/cashfree/06_refunds_and_disputes.md

Cashfree Payments - Refunds & Disputes API

1. Refunds Overview

Cashfree provides programmatic refund capabilities for both full and partial order amounts. Refunds can be initiated directly against any successfully paid order.

Refund Speeds

1. Standard Refund (STANDARD):
   • Follows regular banking clearinghouse cycles.
   • Takes 5 to 7 business days to reflect in the customer's source account/card.
2. Instant Refund (INSTANT):
   • Uses instant payment rails (UPI / IMPS).
   • Credits customer account within seconds or minutes.
   • Requires Instant Refunds to be enabled in Cashfree Dashboard.

---

2. Create a Refund

Endpoint

POST /orders/{order_id}/refunds

• Sandbox: https://sandbox.cashfree.com/pg/orders/{order_id}/refunds
• Production: https://api.cashfree.com/pg/orders/{order_id}/refunds

Request Headers

Content-Type: application/json
x-api-version: 2023-08-01
x-client-id: <APP_ID>
x-client-secret: <SECRET_KEY>
x-idempotency-key: <UUIDv4>

Request Payload Parameters

Field	Type	Required	Description
refund_amount	Number	Yes	Amount to be refunded. Cannot exceed remaining order balance.
refund_id	String	Yes	Unique merchant refund ID (alphanumeric, underscores, hyphens).
refund_note	String	No	Reason or note for the refund (e.g. Customer requested return).
refund_speed	String	No	"STANDARD" (default) or "INSTANT".
refund_splits	Array	No	For split payments (Easy Split marketplace vendors).

Sample Request

{
  "refund_amount": 499.00,
  "refund_id": "tradhox_ref_10029",
  "refund_note": "Partial return for damaged item",
  "refund_speed": "STANDARD"
}

Sample Response (201 Created / 200 OK)

{
  "cf_refund_id": "39104812",
  "cf_payment_id": "291847101",
  "refund_id": "tradhox_ref_10029",
  "order_id": "tradhox_ord_987654",
  "entity": "refund",
  "refund_currency": "INR",
  "refund_amount": 499.00,
  "refund_note": "Partial return for damaged item",
  "refund_status": "SUCCESS",
  "refund_mode": "STANDARD",
  "refund_type": "MERCHANT_INITIATED",
  "refund_arn": "62918401928374",
  "created_at": "2026-10-18T21:15:00Z",
  "processed_at": "2026-10-18T21:15:02Z",
  "status_description": "Refund processed successfully"
}

Note

For Card refunds, refund_arn represents the Acquirer Reference Number (ARN). Provide this number to customers so their issuing bank can trace the credited amount.

---

3. Refund Statuses (refund_status)

Status	Description	Action Required
SUCCESS	Refund processed successfully by Cashfree and partner bank.	Update order/refund record as refunded.
PENDING	Refund is under processing with the customer's bank.	Wait for REFUND_STATUS_WEBHOOK or poll status.
CANCELLED	Refund was cancelled by merchant before processing.	No funds deducted.
FAILED	Bank declined the refund (e.g. account closed, card expired).	Retry or disburse via Payouts directly.

---

4. Get Refund Details

Fetch details and status of a specific refund.

Endpoint

GET /orders/{order_id}/refunds/{refund_id}

---

5. List All Refunds for an Order

Retrieves all refunds (partial or full) issued against an order.

Endpoint

GET /orders/{order_id}/refunds

Sample Response (200 OK)

[
  {
    "cf_refund_id": "39104812",
    "refund_id": "tradhox_ref_10029",
    "order_id": "tradhox_ord_987654",
    "refund_amount": 499.00,
    "refund_status": "SUCCESS",
    "refund_arn": "62918401928374"
  }
]

---

6. Disputes & Chargeback Management

When a cardholder or account owner disputes a transaction with their bank:

Dispute Lifecycle

1. Retrieval Request: Bank requests transaction proof before escalating.
2. Chargeback / Dispute Created: Funds temporarily debited; merchant notified via DISPUTE_CREATED_WEBHOOK.
3. Contest Phase: Merchant submits proof (invoice, AWB tracking, delivery signature).
4. Resolution: Bank or Card Network (Visa/Mastercard) awards dispute to merchant or customer.

Dispute Webhook Payload

{
  "data": {
    "dispute_id": "disp_8291038",
    "order_id": "tradhox_ord_987654",
    "cf_payment_id": "291847101",
    "dispute_amount": 1499.00,
    "dispute_status": "DISPUTE_CREATED",
    "respond_by": "2026-10-25T23:59:59Z",
    "reason_code": "4853",
    "reason_description": "Goods or services not received"
  },
  "event_time": "2026-10-18T21:20:00Z",
  "type": "DISPUTE_CREATED_WEBHOOK"
}