Skip to main content
The Authentication fails when:
  • Test credentials are used in the production environment or vice versa.
  • Client ID and Client Secret are passed in the request body instead of as headers.
  • API keys from different environments are mixed (for example, a Sandbox App ID used with a Production Secret Key).
  • Incorrect API keys are used, such as keys copied incorrectly or taken from a different account.
To troubleshoot this issue, follow these steps:
  • Ensure you are using the correct API keys displayed in the Merchant Dashboard.
  • Use test credentials in the test environment and production credentials in the live environment. For example, use the Client ID and Client Secret generated for the Test/Sandbox environment when making requests to https://sandbox.cashfree.com.
  • When calling the production API, use the Production API Key and Secret Key with the Production endpoint (for example, https://api.cashfree.com/pg/orders/{order_id}). Do not mix Sandbox credentials with the Production endpoint, or vice versa.
  • Pass the Client ID and Client Secret as headers, not in the request body.
  • Ensure both keys are from the same environment.
For more details, refer to the authentication documentation.
This scenario covers multiple concerns, such as server-to-server (S2S) feature is enabled for you, but it isn’t approved for your account or vice versa.To troubleshoot this issue, follow these steps:
  • The prerequisite for S2S is that it requires PCI DSS compliance.
  • To enable it, contact your Account Manager or fill in the Support Form. Once your account is reviewed and approved, this feature will be enabled.
The payment mode that the merchant is trying to make the payment isn’t enabled for the respective account.To troubleshoot this issue, follow these steps:
  • Log in to the Merchant Dashboard and go to Settings > Payment Methods to enable the mode.
  • Alternatively, contact your Account Manager or fill in the Support Form.
If you’re encountering null or empty objects in the Get Order API response, please consider below cases.
  • When no payment is associated with the order yet. ie a payment has not yet been attempted against the Order.
  • If there’s a delay in the payment being recorded due to bank or network delays.
  • You are hitting the Get payments for an order API before your end customer has tried to pay.
To troubleshoot this issue, follow these steps:
  • Please Configure webhooks to receive real-time payment updates.
  • Use the Get Payments for Order API, as the Get Order Status API will only return the order’s current state and not the payment specifics.
The Get Payments for an Order API (GET /pg/orders/{order_id}/payments) returns an empty array ([]) when no payment attempt exists for the order. This happens if the customer opens checkout and then exits, closes the page, or goes back without selecting a payment method such as UPI, card, or netbanking. Cashfree creates a payment object only after the customer selects a method and starts an attempt.Handle the response as follows:
  • Empty array ([]): no payment attempt. Do not treat this as USER_DROPPED. USER_DROPPED appears on a payment object after the customer selected a method and then left the flow.
  • One or more payment objects: use payment_status on each object. Possible values are SUCCESS, FAILED, PENDING, NOT_ATTEMPTED, USER_DROPPED, VOID, and CANCELLED.
The Get Payments for an Order API requires the following headers:
  • x-api-version: the API version you integrate with. Latest is 2026-01-01.
  • x-client-id: your App ID.
  • x-client-secret: your Secret Key.
Platforms that call the API on behalf of merchants use x-partner-apikey and x-partner-merchantid instead of x-client-id and x-client-secret. See API authentication.
Pass the dummy mobile number 9999999999 in the customer_phone field of your Create Order API request to avoid storing payment instrument details such as cards or UPI handles. Cashfree does not store instrument details against this dummy number.
If you’re encountering this issue, please consider below cases.
  • More than two decimal places have been provided for the ‘order_amount’ field. For example, 10.123 or 11089.360 are invalid; 11089.36 is valid.
  • Order Amount is 0 or negative.
  • You have exceeded the maximum amount limit set for your MID.
To troubleshoot this issue, follow these steps:
  • Configure order_amount with a maximum of two decimal places.
  • A minimum amount of one rupee is required.
  • Kindly get the maximum amount limit raised for your Merchant ID. Please contact your Account Manager or fill in the Support Form
If you are on Shopify and the checkout fails to open for high-value orders, check whether the order amount exceeds your account’s configured maximum order amount limit. If the order amount is higher than this limit, the checkout will not load. Contact your Account Manager or fill in the Support Form to request an increase in your maximum order amount limit.
If you’re encountering this issue, please check if your Merchant Category Code (MCC) is under the blocked list for UPI Intent. This feature is not allowed for certain categories of business due to RBI regulations.RBI merchant category restrictions block both UPI Collect (Intent apps) and UPI QR for merchants registered under MCC 6540 (Wallet Loading, Bank Account to Wallet).To troubleshoot this issue, please contact your Account Manager or fill in the Support Form
When a customer enters invalid card details, Cashfree checkout displays an error message so they can correct the details and retry.
For the standard Payment Gateway checkout, customer_phone is a required field during order creation. You cannot omit the phone number or pass an empty value. The standard checkout pre-fills the value you provide and allows the customer to edit it before completing the payment.The phone number does not directly affect the availability of UPI Intent or UPI QR. It is used for checkout personalisation and eligibility, including recommended payment methods, offers, Pay Later eligibility, card saving, and card linking.
No. In the customer_details object, customer_id and customer_phone are required, and customer_email is optional. If you omit customer_email, the order request does not fail validation.
This error occurs when the customer_phone field in the customer_details object is missing or invalid. Pass the phone number in one of the following formats:
  • Indian mobile number: a 10-digit number (for example, 9090407368) or the number with the +91 country code (for example, +919090407368).
  • International number: the number prefixed with + and the country code (for example, +16014635923).
This mismatch can occur when multiple payment attempts are made against the same Order ID. One attempt may fail (for example, due to insufficient funds) while a subsequent attempt succeeds. The Merchant Dashboard reflects the final successful status of the order, but your API response may be capturing one of the earlier failed attempts.To see all payment attempts and their respective statuses for a specific order, use the Get Payments for an Order API.
To retrieve cf_payment_id values, use the Get Payments for an Order API. Pass the order ID as a path parameter. The response returns a list of all payment attempts made for that order, each containing its cf_payment_id.
If the Get Payment by ID API returns NOT_ATTEMPTED while the webhook confirms SUCCESS, verify that you are passing the correct cf_payment_id in the API request path. Ensure you are not passing a phone number or any other session-derived value in the URL path where the API expects the cf_payment_id (for example, /pg/orders/{order_id}/payments/{cf_payment_id}). Always extract the cf_payment_id directly from the Cashfree webhook payload or the initial payment response.
To check the status of a specific payment against an order, use the endpoint https://api.cashfree.com/pg/orders/{order_id}/payments/{cf_payment_id}. This API returns the details of the payment ID passed, including the payment_status field.
You can generate sample API responses for various payment modes by referring to the Order Pay documentation. Within the documentation or testing environment, you can toggle between different payment modes to view their specific response structures.
After creating an order and obtaining a payment_session_id, use the Order Pay API to load the checkout page. You can also use Cashfree Dev Studio for testing and implementation.
An empty response on return_url is expected. The return_url is a browser redirect (GET request) and does not carry a JSON response body. To receive programmatic payment status updates, configure a separate webhook endpoint (notify_url), which receives server-to-server POST notifications. You can also fetch the final status using the Get Order API once the customer returns to your site.
Both return_url and notify_url must be within a maximum of 250 characters. Using long wrapped URLs or security proxies that exceed this limit can cause integration issues.
An order_not_found error during the Create Order API call can occur due to a brief propagation or replication delay between systems. In this scenario, the order is successfully created in the backend but the API response fails to find it immediately. To verify whether the order exists, call the Get Order API (GET /pg/orders/{order_id}) shortly after receiving the error. If the order is returned as ACTIVE, the order record exists and is awaiting payment. No customer charges have occurred at this stage.
This error often occurs due to a mismatch between the terminal used to create the order and the terminal used in the transaction call. Ensure that the terminal_id passed in the Create Order request exactly matches the cf_terminal_id or terminal_id used in the POST /pg/terminal/transactions call for that specific order.
UPI Intent works by default on mobile browsers for standard web checkout without requiring special implementation or feature flags. Your backend calls the Create Order API to generate a payment_session_id, and the frontend loads the Cashfree Checkout JS SDK. UPI Intent options (GPay, PhonePe, and others) appear automatically when the checkout page is accessed via a mobile browser.For more details, refer to the web integration documentation.
The channel_invalid error in the Sessions API occurs when the value provided in the channel field of the payment_method object is not accepted for that specific payment method. For certain wallet or PPI (Prepaid Payment Instrument) transactions, link is the only allowed value for the channel.
No. Cashfree simulates every step of a Sandbox payment, with no real-time transfer to NPCI or the bank. No NPCI UAT route exists, and NPCI cannot resolve Sandbox VPAs. Real NPCI paths can only be exercised in the Production environment on a live account with procured terminals.
If your checkout interface appears basic or outdated, you may be using the Drop Checkout flow, which is deprecated and no longer under active development. To use the latest Cashfree Checkout UI, migrate to the latest Web Checkout flow. For mobile integrations such as React Native, see Select a payment flow in the React Native integration guide.
Cashfree associates saved UPI IDs and cards with the customer’s phone number in the order request. If you create a new order with a different customer phone number, the previously saved instruments do not appear for that user. To keep users isolated from each other, pass a unique and correct customer_phone for each user in the Create Order API request.
Yes. Cashfree lets you disable saved instruments (saved cards and UPI IDs) at the merchant account level. If you do not want Cashfree to display previously used payment methods to your customers, contact your Account Manager or fill in the Support Form to disable this feature for your account.
Yes. A payment_session_id that contains the suffix paymentpayment is expected behaviour, not a malformed value. The session ID still functions correctly for opening the checkout.