paytm-troubleshooting

name	paytm-troubleshooting
description	Symptom -> cause -> fix tree for Paytm integration failures: checksum mismatches (227), invalid / duplicate orderId (330/334), bad request (400), JS Checkout modal not opening, callback verification failures, transaction-status confusion, refund pending, and corp-proxy TLS interception (`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`). Includes the expanded RESPCODE reference and a top-level decision tree. Load this skill when the user reports an error code, an unexpected behavior, or asks "why is X failing?" in a Paytm context.
triggers	["resultCode: 227","resultCode: 330","resultCode: 334","resultCode: 400","RESPCODE","checksum mismatch","UNABLE_TO_GET_ISSUER_CERT_LOCALLY","MISSING_TXN_TOKEN"]

Paytm Troubleshooting

Symptom-driven debugging. Always start at the decision tree, then dive into the matching section in references/REFERENCE.md.

This skill is split across two files. SKILL.md (this file) gives the decision tree + quick RESPCODE lookup. references/REFERENCE.md contains per-symptom deep dives: Initiate Transaction failures by code, "Pay button does nothing" causes, JS Checkout render issues, callback verification failures, refund-stuck-PENDING, the corp-proxy TLS interception fix (with extracted CA commands per OS), and full env / config gotchas — all NOT repeated here.

Do not propose a fix for a Paytm integration error until you have read references/REFERENCE.md.

---

Decision tree

Payment failed?
├─ Did initiateTransaction return a txnToken?
│   ├─ No  -> check resultInfo.resultMsg -> "Initiate Transaction fails" in REFERENCE
│   └─ Yes
│       ├─ Did JS Checkout render?
│       │   ├─ No  -> "JS Checkout doesn't render" in REFERENCE
│       │   └─ Yes
│       │       ├─ Did Paytm POST callback?
│       │       │   ├─ No  -> call Transaction Status API anyway (browser issue)
│       │       │   └─ Yes
│       │       │       └─ Did CHECKSUMHASH verify?
│       │       │           ├─ No  -> "Callback arrives but is ignored" in REFERENCE
│       │       │           └─ Yes -> call /v3/order/status - that is the truth

---

Top-of-page RESPCODE / resultCode reference

Code	Meaning	First check
01	Txn success	Fulfill order
141	User cancelled at bank page	Allow retry
227	Checksum mismatch	Body bytes used to sign must equal bytes sent. MERCHANT_KEY quoted in .env. Wrong env (staging key on prod host).
235	Insufficient bank balance	Show retry / different option
267	Bank declined	Retry / switch option
295	Invalid card details	User error
334	Duplicate orderId	Generate new orderId per attempt
335	Request expired	Server clock skew / stale request
400	Bad request	Missing required field; check websiteName matches dashboard
401	Unauthorized	MID/key mismatch, env mismatch
402	Pending - awaiting bank	Poll Transaction Status
501	System error	Retry
810	Risk system declined	Contact Paytm support
911 / BANK_PENDING	Bank confirmation pending	Poll, do not refund
4001	Subscription: grace > frequency	Drop subscriptionGraceDays or set < cycle length
5007	Payment Link: invalid char in linkName	Strip spaces — linkName is alphanumerics only
GW00460	Custom SDK / WebView: "Invalid tranportal id" — stale txnToken reused on retry	Treat every txnToken as single-use. On retry, fetch a fresh txnToken AND a fresh orderId (timestamp-suffix the orderId). See custom-sdk skill § Bug A.
ENOTFOUND / "Cannot resolve hostname" on a previously-working integration	Stale process state after VPN toggle / sleep-wake / Wi-Fi handover. NOT a code bug.	lsof -ti:<port> | xargs kill -9 && npm start. Verify with dig, curl, fresh node -e "dns.lookup(...)" first. See references/REFERENCE.md § ENOTFOUND.
notifyMerchant should be of function type (or transactionStatus should be of function type); modal opens then UI sits stuck	Handler declared as async function (...) {} — CheckoutJS rejects AsyncFunction. Even when the type check passes, CheckoutJS does NOT await the handler, so awaited work runs after the modal disposes.	Use plain function (...) {}. Dispatch any async work via .then / .catch, never await inline. See js-checkout skill § Handlers must be plain functions.

For unfamiliar codes, query /v3/order/status with the orderId — body.resultInfo.resultMsg is canonical.

---

When to look in REFERENCE

references/REFERENCE.md has full sections on:

• Initiate Transaction failures (per resultCode)
• "Failed to parse URL from /paytm/create-order" (SSR issue)
• "Pay" button does nothing (the onLoad trap, popup blocker, expired token)
• JS Checkout doesn't render
• Callback arrives but is ignored / treated as failure
• Transaction Status mismatches
• Refund pending / stuck
• Corp proxy TLS interception — UNABLE_TO_GET_ISSUER_CERT_LOCALLY, asymmetric MITM, SSL_CERT_FILE vs NODE_EXTRA_CA_CERTS semantics, OS-specific CA extraction commands
• Environment / config gotchas (PG domain mismatch, websiteName, currency)

Open the reference, jump to the matching heading.

---

Skill cross-reference

The reference is symptom-organized. If the symptom is product-specific:

• Subscription error codes → also see subscriptions skill
• Payment Link error codes → also see payment-links skill
• Webhook signature failures → also see webhooks skill
• Card / Net Banking simulator behavior → also see js-checkout skill