Cashfree uses a different auth pattern from Razorpay: two custom headers instead of Basic Auth, plus a required API version header. This guide gives you the exact values for every field in the External API Request step.
Cashfree is a popular Indian payment gateway with strong UPI, card, and net banking support. Its API uses custom headers rather than standard Basic Auth, and requires a version header on every request. Once you know these three header values, the setup is straightforward.
New to the External API Request step? Read the foundation guide first.
Cashfree issues different App IDs and Secret Keys for sandbox and production. Switching from test to live requires updating both header values. The endpoint base URL also changes from sandbox.cashfree.com/pg to api.cashfree.com/pg.
Unlike most APIs that need only one auth header, Cashfree requires three: x-client-id, x-client-secret, and x-api-version. Missing any one will return an authentication or validation error. The version value 2025-01-01 is current as of mid-2026; check Cashfree's changelog if you get an api_version error.
| Environment | Base URL |
|---|---|
| Sandbox (testing) | https://sandbox.cashfree.com/pg/orders |
| Production (live) | https://api.cashfree.com/pg/orders |
{
"order_id": "order_{{unique_id}}",
"order_amount": 500.00,
"order_currency": "INR",
"customer_details": {
"customer_id": "cust_{{customer_phone}}",
"customer_name": "{{customer_name}}",
"customer_email": "{{customer_email}}",
"customer_phone": "{{customer_phone}}"
},
"order_meta": {
"return_url": "https://yoursite.com/payment-success?order_id={order_id}"
}
}order_id must be unique per transaction. A common approach is to combine a prefix with a timestamp or your internal order number. order_amount is in rupees (not paise, unlike Razorpay).
{
"order_id": "order_12345",
"order_status": "ACTIVE",
"payment_session_id": "session_...",
"order_expiry_time": "2026-06-22T18:30:00+05:30"
}For WhatsApp, the most practical option is to construct the Cashfree payment URL directly from the order_id. Cashfree's hosted payment page follows a predictable URL pattern, or you can use the payment_session_id with Cashfree's JavaScript SDK on a web page. For a simple WhatsApp link, many businesses direct customers to their own checkout page that loads the Cashfree SDK with the session ID from this response.
For the full response schema and the hosted checkout URL pattern, see docs.cashfree.com/docs/create-order.
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 Unauthorized | Wrong App ID or Secret Key | Re-check both values; confirm you are using sandbox credentials with the sandbox URL |
| 422 Unprocessable | Missing or invalid x-api-version header | Add x-api-version: 2025-01-01 to the headers |
| order_id already exists | Duplicate order ID | Use a unique value per order; append a timestamp or UUID |
| Customer phone invalid | Phone number format wrong | Use a 10-digit Indian mobile number without the country code in customer_phone |
| Response from wrong environment | Mixing sandbox keys with production URL | Check that sandbox keys go to sandbox.cashfree.com and live keys go to api.cashfree.com |
Basic Auth, payment links with short_url.
Read guide →Bearer auth, for international payments from India.
Read guide →Foundation guide.
Read guide →Automate follow-up on unpaid orders.
Read guide →Send UPI payment requests inside WhatsApp.
Read guide →All connection guides.
Browse all →Free trial, no credit card required. And if you ever get stuck, we are the only platform in India that answers you live on WhatsApp.