paymentservice/documentation/cashfree/10_error_codes_and_test_data.md

Cashfree Payments - Error Codes & Sandbox Test Data

1. Error Response Structure

All Cashfree Payment Gateway APIs return consistent JSON error objects when a request fails:

{
  "message": "Order with id 'tradhox_ord_987654' is already paid",
  "code": "order_already_paid",
  "type": "invalid_request_error"
}

Top-Level Error Types (type)

Error Type	HTTP Status	Meaning
invalid_request_error	400, 404, 409	Malformed body, missing required parameters, invalid IDs, or invalid state transitions.
authentication_error	401	Invalid or missing x-client-id, x-client-secret, or expired tokens.
rate_limit_error	429	Request volume exceeded allowed threshold. Implement backoff.
api_error	500, 502, 503	Temporary server-side issue at Cashfree or partner bank.

---

2. Common API Error Codes

Error Code (code)	HTTP Status	Description & Recommended Handling
order_already_paid	400	The order has already been successfully paid. Do not prompt user again; fetch order status.
order_expired	400	The order has passed its order_expiry_time. Generate a new order.
order_terminated	400	The order was marked as terminated.
order_not_found	404	No order exists matching the provided order_id. Verify ID spelling.
duplicate_order_id	409	An order with this order_id already exists. Use a unique order ID generator.
idempotency_conflict	409	The same x-idempotency-key was submitted with a different request payload.
invalid_customer_details	400	Phone number is not 10 digits or email format is invalid.
payment_declined	400	Customer's issuing bank declined the card or UPI payment.
insufficient_balance	400	Insufficient balance in merchant account to process instant refund or payout.
unauthorized_ip	401	Calling server IP is not in your Merchant Dashboard IP Whitelist.

---

3. Sandbox Test Credentials & Simulators

When testing in the Sandbox environment (https://sandbox.cashfree.com/pg):

1. Test Cards

Card Type	Card Number	Expiry	CVV	Expected Result
Visa (Success)	4012 0010 3714 1112	Any future date (e.g. 12/28)	123	SUCCESS (3DS OTP: 123456)
Mastercard (Success)	5123 4567 8901 2346	Any future date	123	SUCCESS
RuPay (Success)	6071 2345 6789 0123	Any future date	123	SUCCESS
Card Declined	4012 0010 3714 1113	Any future date	123	FAILED (payment_declined)
Insufficient Funds	4012 0010 3714 1114	Any future date	123	FAILED (insufficient_funds)
3DS Timeout	4012 0010 3714 1115	Any future date	123	FAILED (user_dropped)

Test 3D-Secure OTP

On the simulated bank OTP page, enter 123456 or click the Success button.

---

2. Test UPI Handles

VPA / UPI ID	Action / Behaviour
success@upi	Auto-approves payment; triggers instant PAYMENT_SUCCESS_WEBHOOK.
failure@upi	Auto-declines payment; returns bank refusal.
test@okhdfcbank	Simulates UPI Intent and Collect prompt.

---

3. Test Netbanking

Select any major bank (e.g. HDFC, ICICI, SBI) in Sandbox Checkout. Cashfree displays a mock banking portal with options:

• Success: Simulates customer approving netbanking login and OTP.
• Fail: Simulates bank session timeout or incorrect credentials.
• Pending: Simulates delayed bank settlement.