Root Cause Diagnosis
A UPI payment is a multi-leg flow: the payer’s PSP app sends a collect/pay request through NPCI, the remitter bank debits the payer, and NPCI then instructs the beneficiary bank to credit the merchant’s VPA or account. “Success” at the sender bank only confirms the debit leg. If the credit leg times out, the beneficiary bank or PSP is down, or the merchant’s acquirer fails to return a final response, the transaction sits in a deemed or pending state (NPCI response codes such as U30, U09, U16, BT, RB) and the merchant system never receives a success callback. The result is a debit with no credit that is resolved either by a late credit or by an automatic reversal (TCC/RET), not by a retry from the payer.
Quick Fix
Do not retry the payment. Collect the 12-digit UPI Ref No. (RRN) and Transaction ID from the payer’s app, then check the final status on the merchant side.
For merchants using a payment gateway API, query the order status directly (Razorpay example):
curl -u <KEY_ID>:<KEY_SECRET> \
https://api.razorpay.com/v1/payments?order_id=order_XXXXXXXX
Look at status (captured, authorized, failed) and error_code. If the gateway shows captured, the money has reached the merchant and the issue is on the merchant’s webhook or order system (see Step 5). If it shows failed or no record, wait for auto-reversal (see Step 6).
Step-by-Step Resolution
1. Collect the identifiers from the payer
Required to trace the transaction at every layer:
- UPI Ref No. / RRN (12 digits)
- UPI Transaction ID (starts with the PSP handle, for example
AXI...,YBL...,PTM...) - Amount, debit timestamp, payer VPA, and merchant VPA
- Payer bank debit SMS or statement entry
2. Check the transaction status in the payer app
In the payer’s UPI app, open Transaction History → select transaction → View Details. Note the status wording:
| Status | Meaning | Action |
|---|---|---|
| Success / Completed | Debit and credit both confirmed by NPCI | Merchant must reconcile (Step 4) |
| Pending / Processing | Awaiting beneficiary bank response | Wait up to T+1 working day |
| Failed, amount debited | Credit failed, reversal due | Wait for auto-reversal (Step 6) |
| Deemed Approved | NPCI timed out, credit assumed | Merchant checks bank statement and PSP report |
3. Verify status through the merchant’s PSP or acquirer
Search by RRN in the gateway dashboard or settlement report:
- Razorpay: Dashboard → Transactions → Payments, search RRN or payment ID.
- PhonePe PG: Merchant Dashboard → Transactions, search merchant transaction ID.
- Cashfree: Payment Gateway → Transactions → Search.
- Direct bank UPI (VPA/QR): check the UPI Collections / Credit Report in the net banking portal, which lists RRN-wise credits.
If the gateway lists the payment as captured or SUCCESS, the credit leg is complete and funds follow the settlement cycle (T+1 or T+2 for most gateways, not instant).
4. Reconcile using the status check API
Never rely only on the redirect or callback. Poll the server-to-server status API for every transaction left in a pending state:
# Generic pattern: query by merchant transaction ID
curl -X GET "https://<gateway-host>/v1/orders/<ORDER_ID>/payments" \
-H "Authorization: Bearer <TOKEN>"
Recommended polling schedule for pending transactions, following NPCI guidance: check at 30 seconds, then every 60 to 120 seconds for the first 10 minutes, then at 1 hour, 6 hours, and 24 hours. Stop at a terminal state (SUCCESS, FAILURE).
5. Fix webhook and callback failures on the merchant side
If the gateway shows success but the merchant system shows unpaid, the callback was not processed.
# Verify the webhook signature, then mark the order paid idempotently
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
Check these points:
- The webhook endpoint returns HTTP
200within the gateway’s timeout (usually 5 to 10 seconds). Return200first and process asynchronously. - The endpoint is reachable from the gateway: no WAF block, no auth redirect, valid TLS certificate.
- Handling is idempotent on the payment ID, so retries do not double-credit.
- Use the gateway’s Webhooks → Logs → Resend option to replay missed events.
6. Wait for auto-reversal when the credit failed
If the payer’s debit stands, the merchant has no credit, and the gateway shows failed, the beneficiary-side leg failed and NPCI’s Transaction Credit Confirmation/Return process applies. Under the RBI TAT harmonisation framework, the standard timeline is:
- Failed UPI transaction with debit: automatic reversal by T+1 working day.
- If not reversed, the bank owes compensation of ₹100 per day for delay beyond the timeline, credited to the customer without a claim in most cases.
7. Escalate in the correct order
- Payer bank or UPI app support, quoting RRN and transaction ID, and ask for a raised chargeback or dispute.
- Merchant’s PSP/acquirer, if the merchant account is expected to show the credit.
- UPI Dispute Redressal Mechanism inside the app: Profile → Help → Select transaction → Raise Dispute.
- NPCI, after the bank’s resolution period: npci.org.in → UPI → Dispute Redressal Mechanism → File a complaint, with RRN and bank responses attached.
- RBI Integrated Ombudsman at cms.rbi.org.in, if the bank does not resolve within 30 days of the complaint.
Why This Fails for Some Users
- Deemed approved transactions: NPCI treats a timed-out credit as deemed success and settles it later during batch reconciliation. Merchants who query only the real-time API may see no record until the next settlement cycle, so check the settlement or reconciliation report as well.
- Settlement delay mistaken for non-credit: Payment gateways credit the merchant’s bank account on a T+1 or T+2 basis, and weekends and bank holidays extend it. A
capturedpayment is not yet in the bank account. - Wrong or invalid VPA mapping: If a merchant’s VPA is linked to a closed, dormant, or frozen account, or the merchant changed the primary bank without updating the VPA, the beneficiary bank rejects the credit, which then gets returned to the payer.
- Beneficiary bank downtime: Scheduled or unscheduled downtime at the beneficiary bank or the PSP (check NPCI’s UPI performance page for per-bank success rates) delays credits for hours. The transaction resolves without any action by either party.
- Daily limits and account restrictions: Merchant-side account limits, KYC-pending status, or flagged risk can hold the credit as pending. These show as
U66or similar codes, and the bank must lift the hold. - Duplicate-looking payments: Payers who retry after seeing a pending state may trigger two debits. Verify against RRNs, because the second is a separate transaction that needs its own reversal or credit.
- UPI Lite and offline wallet payments: UPI Lite debits happen from the on-device balance and settle in batches, so the merchant sees the credit later than with a normal UPI payment. Reversals follow a different process.
- Cross-border and third-party app (TPAP) flows: International UPI (for example at foreign merchants) and certain TPAP handles use extra intermediary hops, which lengthen the reversal and credit timelines.
- Merchant reconciling by amount instead of RRN: Matching on amount and time produces false mismatches when two payers send identical amounts. Reconcile on RRN and the gateway’s payment ID only.
- Rules change over time: TAT, compensation amounts, and dispute channels are revised by NPCI and RBI circulars. Verify current values at npci.org.in and rbi.org.in before quoting them to a customer.