> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments Troubleshooting

> Troubleshoot Cashfree integration issues including authentication failures, order creation errors, UPI flow problems, and checkout configuration.

<Accordion title="Authentication failed" onClick={() => posthog.capture('Accordion Clicked', { title: "Authentication failed" })}>
  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](https://merchant.cashfree.com/auth/login).
  * 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](/docs/api-reference/authentication).
</Accordion>

<Accordion title="S2S_enabled_not_approved or POST/orders/pay is not enabled or approved" onClick={() => posthog.capture('Accordion Clicked', { title: 'S2S_enabled_not_approved" or "POST/orders/pay is not enabled or approved' })}>
  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](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1). Once your account is reviewed and approved, this feature will be enabled.
</Accordion>

<Accordion title="Payment mode not enabled for merchant" onClick={() => posthog.capture('Accordion Clicked', { title: "Payment mode not enabled for merchant" })}>
  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](https://merchant.cashfree.com/auth/login) and go to **Settings > Payment Methods** to enable the mode.
  * Alternatively, contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1).
</Accordion>

<Accordion title="Unable to delink existing AmazonPay wallet and add a new one" onClick={() => posthog.capture('Accordion Clicked', { title: "Unable to delink existing AmazonPay wallet and add a new one" })}>
  To troubleshoot this issue, follow these steps:

  * The user needs to log out of the Amazon account from that system, clear the browser cache and try once again.
</Accordion>

<Accordion title="Null objects in Get Order / Payment API response" onClick={() => posthog.capture('Accordion Clicked', { title: "Null objects in Get Order / Payment API response" })}>
  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.
</Accordion>

<Accordion title="Why does the Get Payments for an Order API return an empty array?" onClick={() => posthog.capture('Accordion Clicked', { title: "Why does the Get Payments for an Order API return an empty array?" })}>
  The [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) (`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`.
</Accordion>

<Accordion title="Which headers does the Get Payments for an Order API require?" onClick={() => posthog.capture('Accordion Clicked', { title: "Which headers does the Get Payments for an Order API require?" })}>
  The [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order) 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](/docs/api-reference/authentication).
</Accordion>

<Accordion title="How do I avoid storing payment instrument details during checkout?" onClick={() => posthog.capture('Accordion Clicked', { title: "How do I avoid storing payment instrument details during checkout?" })}>
  Pass the dummy mobile number `9999999999` in the `customer_phone` field of your [Create Order API](/docs/api-reference/payments/latest/orders/create-order) request to avoid storing payment instrument details such as cards or UPI handles. Cashfree does not store instrument details against this dummy number.
</Accordion>

<Accordion title="Order Amount Invalid" onClick={() => posthog.capture('Accordion Clicked', { title: "Order Amount Invalid" })}>
  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](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
</Accordion>

<Accordion title="UPI Intent not visible on checkout" onClick={() => posthog.capture('Accordion Clicked', { title: "UPI Intent not visible on checkout" })}>
  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.

  To troubleshoot this issue, please contact your Account Manager or fill in the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1)
</Accordion>

<Accordion title="How does Cashfree handle invalid card details on the checkout page?" onClick={() => posthog.capture('Accordion Clicked', { title: "How does Cashfree handle invalid card details on the checkout page?" })}>
  When a customer enters invalid card details, Cashfree checkout displays an error message so they can correct the details and retry.
</Accordion>

<Accordion title="Is customer_phone required during order creation?" onClick={() => posthog.capture('Accordion Clicked', { title: "Is customer_phone required during order creation?" })}>
  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.
</Accordion>

<Accordion title="Why does my API response show a failed payment status while the Merchant Dashboard shows the order as successful?" onClick={() => posthog.capture('Accordion Clicked', { title: "Why does my API response show a failed payment status while the Merchant Dashboard shows the order as successful?" })}>
  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](/docs/api-reference/payments/latest/payments/get-payments-for-an-order).
</Accordion>

<Accordion title="How do I retrieve the cf_payment_id for an order?" onClick={() => posthog.capture('Accordion Clicked', { title: "How do I retrieve the cf_payment_id for an order?" })}>
  To retrieve `cf_payment_id` values, use the [Get Payments for an Order API](/docs/api-reference/payments/latest/payments/get-payments-for-an-order). 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`.
</Accordion>

<Accordion title="Why does the Get Payment by ID API return NOT_ATTEMPTED even though the webhook reports SUCCESS?" onClick={() => posthog.capture('Accordion Clicked', { title: "Why does the Get Payment by ID API return NOT_ATTEMPTED even though the webhook reports SUCCESS?" })}>
  If the [Get Payment by ID API](/docs/api-reference/payments/latest/payments/get-payment-by-id) 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.
</Accordion>

<Accordion title="Which API should I use to check the status of a payment for a specific order?" onClick={() => posthog.capture('Accordion Clicked', { title: "Which API should I use to check the status of a payment for a specific order?" })}>
  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.
</Accordion>

<Accordion title="How can I see sample API responses for different payment modes?" onClick={() => posthog.capture('Accordion Clicked', { title: "How can I see sample API responses for different payment modes?" })}>
  You can generate sample API responses for various payment modes by referring to the [Order Pay documentation](/docs/api-reference/payments/latest/payments/order-pay). Within the documentation or testing environment, you can toggle between different payment modes to view their specific response structures.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.