Checkout works in the demo. The support tickets come later: a customer whose money was debited but whose order shows failed, a payment stuck in pending for an hour, or a refund that was promised but never arrived. These are not rare edge cases. They are normal behaviour in a system that depends on many banks and apps, and your integration has to expect them.
This guide covers the payment states you need to model, what to do when money is debited for a failed order, how to verify Cashfree webhooks and statuses, how to design refunds that cannot be duplicated, and what customers and support staff should see.
Quick answer: Let only your server decide a payment's outcome, using verified Cashfree webhooks and the order status API, never the return URL alone. Keep pending orders open and re-check them on a schedule, decide in advance what happens when a failed payment later succeeds, and issue refunds through the refund API with a refund ID you generate once, so retries never create a second refund.
The payment states you need to model
Cashfree reports a status for each payment attempt against an order, with values such as SUCCESS, FAILED, PENDING and USER_DROPPED. One order can have several attempts, for example a failed card payment followed by a successful UPI payment. Map each state to a clear action:
| State | What it usually means | What your system should do |
|---|---|---|
| Success | The payment is confirmed | Mark the order paid once, fulfil it and send the receipt |
| Failed | The bank or app declined it, or the customer entered a wrong PIN or OTP | Keep the order open and offer a retry with another method |
| Pending | A bank has not yet confirmed the result; common with UPI and net banking | Show "confirming payment", re-check on a schedule and do not cancel yet |
| User dropped | The customer left checkout without completing | Keep the cart and, if you wish, send a reminder with a fresh payment link |
| Order expired | The order passed its expiry time without a successful payment | Close it; any later attempt needs a new order |
| Refund pending or processed | A refund is in progress or completed | Update the order, the ledger and the customer |
Store every attempt, not just the latest status. When a customer calls, your support team needs the full history.
When money is debited but the order shows failed
This is the most common complaint. It happens when the customer's bank debits the account but the confirmation is delayed or times out somewhere along the chain. Usually one of two things follows: the payment is confirmed as successful a little later, or it fails and the bank reverses the debit to the customer. Decide your rules before launch:
- Late success: If a payment you showed as failed is later confirmed, either fulfil the order automatically or, if stock or a slot is no longer available, refund it automatically and tell the customer. Do not rely on someone noticing it in the dashboard.
- Duplicate payments: A customer who sees a failure often pays again. If both payments succeed, refund the extra one automatically.
- Honest messaging: Show "We are confirming your payment" rather than "Payment failed" while the status is pending, and tell customers you will update them.
- Reversal timelines: Reversal of a failed debit is handled by the banks and payment systems involved. RBI has issued a framework on turnaround times and customer compensation for failed transactions; check the current circular on rbi.org.in and avoid promising customers a specific date yourself.
Verify every status on the server
The return URL that brings the customer back to your site is useful for showing a page, but it is not proof of payment. Confirm the result on the server:
- Webhooks: Cashfree sends signed webhook notifications for payment and refund events. Verify the signature, an HMAC-SHA256 computed over the timestamp header and the raw request body with your secret key, before trusting the payload. The official SDKs include a verification helper.
- Status API: When the customer returns, and for any order still pending, fetch the order and its payments from Cashfree's API and act on that response.
- Scheduled checks: A background job re-checks orders that stay pending beyond a set time, so a missed webhook does not leave an order stuck.
- Idempotent updates: Webhooks can repeat. Use the Cashfree payment ID as a unique key so the same success cannot fulfil an order twice.
Before fulfilling, also compare the amount and currency of the confirmed payment with the order in your database.
Designing refunds that cannot go wrong
Refunds move money out of your account, so they deserve the same care as payments:
- Generate the refund ID yourself: Cashfree's refund API takes a refund ID that you supply. Create it once, store it, and reuse it if the call times out and you retry. Test in the sandbox how a repeated refund ID is handled.
- Cap partial refunds: The total of all refunds against a payment must never exceed the amount captured. Enforce this in the database, not only in the admin screen.
- Control who can refund: Give refund rights to specific roles, require approval above an amount you choose, and log who approved each one.
- Track to completion: A refund request is not a completed refund. Listen for refund webhooks, show the status in your admin panel and alert your team if a refund stays pending or fails.
- Share references: Where a bank reference for the refund is available, show it to the customer so they can trace it with their bank.
- Expect settlement impact: Refunds are usually adjusted against upcoming settlements, so your reconciliation should expect lower credits after heavy refund days.
Some refunds cannot go back to the original method, such as cash-on-delivery orders. For those, a verified bank or UPI payout is cleaner than a manual transfer; our payout API integration service covers that flow.
What customers and support staff should see
Payment complaints turn angry when nobody can answer them. Give your team a payment screen that shows, for each order:
- Every attempt with its method, time, amount and Cashfree payment ID
- The bank reference or UPI reference number once available
- Webhooks received and when the status was last checked
- Refund requests with their IDs, status and approver
Send customers an automatic message at each change: payment confirmed, payment failed with a retry link, refund initiated, refund completed. A clear trail settles most disputes before they start. If you are planning a new build, our Cashfree integration service includes this failure and refund handling as standard.
How EthicsComputer can help
We integrate the Cashfree payment gateway, refunds and payouts on your own Cashfree account, with signature-verified webhooks, status checks, refund controls and daily settlement matching. See what our Cashfree integration work covers, or look at payment reconciliation software if your finance team is matching refunds and settlements by hand.
Losing time to debited-but-failed payment complaints?
Share how your checkout and refunds work today, and we will suggest how to close the gaps.
About the author
Vinay Grover founded EthicsComputer in Rohtak, Haryana in 2018 and leads its cybersecurity, software and AI work for clients across India and abroad. EthicsComputer is ISO 9001, ISO/IEC 27001 and ISO 20000-1 certified.