paytm-agent-skills

Complete JS Checkout (one-time payment) flow for Paytm Payment Gateway: Generate Checksum -> Initiate Transaction (txnToken) -> Render JS Checkout -> Handle Callback -> Transaction Status verification. Covers the merchant CheckoutJS script, init/invoke pattern, callback verification (`/v3/order/status`), and the most common bugs (`CheckoutJS.onLoad` trap, missing `transactionStatus`/`notifyMerchant` handlers, debug dumps on the user-facing screen). Load this skill for ALL one-time web payments (checkout pages, "Pay" buttons, in-app payments). Do NOT load for subscriptions, links, or QR.

Paytm UPI Autopay / Native Subscription flow for recurring charges (monthly / weekly / yearly / daily mandates, SIPs). Covers `POST /subscription/create` with `requestType: NATIVE_SUBSCRIPTION`, the flat-body field placement (no `subscriptionDetails` wrapper), required `head.clientId` / `channelId` / `signature`, the `traceId` query param, retry / grace rules, default value choices, and the most common errors (4001 grace > frequency, custId sanitization, etc.). Also covers the full post-consent recurring lifecycle (`subscription/checkStatus`, `renew`, `preNotify`, `cancel`, `v3/order/status`), the `/theia/` vs non-`/theia/` host split, and subscription webhook events (`SUBSCRIPTION_DEBIT` / `SUBSCRIPTION_CANCEL`) — see `references/recurring-lifecycle.md`. Load this skill for ANY recurring charge - "subscription", "monthly", "autopay", "mandate", "renew every…", "membership", "plan", "SIP". Do NOT load for one-time payments.

Paytm Large Payment Collection (Bank Transfer) — accept high-ticket payments via NEFT / RTGS / IMPS (UPI also supported in the Checkout flow) using a unique 18-char Virtual Account Number (VAN) per customer / order. Paytm auto-reconciles the inbound bank transfer to the right VAN, fires a webhook with full remitter details, and settles T+1. Two integration shapes: the **Checkout flow** (default — order-based VAN issued via /initiateTransaction, surfaced inside the Paytm JS Checkout modal) and the **Non-Checkout flow** (server-only permanent VANs via the vanproxy API for ongoing collections — BFSI, schools, distributors, subscriptions). Covers Create VAN, Query VAN, Update VAN (disable / TPV), VAN List, Order List, Transaction Status, Refund, Refund Status, and payment / refund webhooks. Load this skill for "bank transfer collection", "virtual account", "VAN", "NEFT/RTGS/IMPS collection", "large payment", "bulk collection", "fee collection", "invoice bank transfer".

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.

Migration playbook for moving from BillDesk (PG by BillDesk / IndiaIdeas.com) to Paytm Payment Gateway. BillDesk merchants typically run one of two flows: the legacy pipe-delimited PaymentRequest flow (HMAC-SHA256 checksum on `|`-joined message string) OR the newer Online Payment v1.2 API (JWS-signed + JWE-encrypted JSON over `/payments/ve1_2/orders/create`). Covers both flows, mapping to Paytm's JSON + checksum REST model, recurring (BillDesk eMandate) -> NATIVE_SUBSCRIPTION, refund + status flow, and dual-write rollout. Load when the user mentions migrating from BillDesk or has BillDesk integration in the codebase (BILLDESK_MERCHANT_ID, BILLDESK_CLIENT_ID, BILLDESK_SECRET_KEY, pgi.billdesk.com, /pgidsk/PGI*, /payments/ve1_2/, BdSign JWS, BdJwe payload).

Migration playbook for moving from Cashfree Payments (Payment Gateway, Subscriptions, Payouts, Easy Split) to Paytm Payment Gateway. Covers the Cashfree session/order model -> Paytm's `txnToken` + JS Checkout, X-Client-Id / X-Client-Secret header auth -> Paytm body checksum, webhook signature scheme, recurring payments, refunds, and dual-write rollout. Load when the user mentions migrating, switching, or moving from Cashfree to Paytm, or has a Cashfree integration in the codebase (e.g. `cashfree-pg`, `Cashfree.PG.Orders.CreateOrder`, `cashfreepayments.com`, `CASHFREE_APP_ID`, `CASHFREE_SECRET_KEY`, `x-client-id` headers, `payment_session_id`, `/pg/orders`).

Migration playbook for moving from CCAvenue (Avenues India) to Paytm Payment Gateway. CCAvenue uses an AES-256 encrypted form-POST flow with three credentials (merchant_id, access_code, working_key) — substantially different from Paytm's JSON+checksum REST flow. Covers the AES-encrypted-form -> REST JSON shift, request/response encryption translation, Subscription Information (SI) -> NATIVE_SUBSCRIPTION, billing/shipping field reduction, refund cancellation via the non-seamless API, and dual-write rollout. Load when the user mentions migrating from CCAvenue or has CCAvenue integration in the codebase (CCAVENUE_MERCHANT_ID, CCAVENUE_ACCESS_CODE, CCAVENUE_WORKING_KEY, AES-256, secure.ccavenue.com, /transaction/transaction.do).

Migration playbook for moving from Juspay (HyperSDK / Hyper Checkout / ExpressCheckout API) to Paytm Payment Gateway. Juspay is an orchestrator that routes through multiple underlying PGs; moving to Paytm means accepting Paytm as the single PG, losing the multi-PG routing / smart-retry layer. Covers the orchestrator -> direct-PG mental shift, HyperSDK -> Paytm All-in-One SDK, ExpressCheckout REST -> Paytm /theia/api/v1/initiateTransaction, webhook scheme, refunds, and dual-write rollout. Load when the user mentions migrating from Juspay, or has Juspay integration code (HyperSDK, hyperServices, juspay.in, /orders endpoint, JUSPAY_API_KEY, juspay-node, in.juspay.hypersdk).

Migration playbook for moving from PayU India (PayU Money / PayU Biz / Enterprise) to Paytm Payment Gateway. Covers the form-POST checkout model -> Paytm's JS Checkout JSON model, PayU's hash scheme (SHA-512 over pipe-joined string) -> Paytm checksum, recurring payments, refunds, and dual-write rollout. Load when the user mentions migrating, switching, or moving from PayU to Paytm, or has an existing PayU integration in the codebase (e.g. PayU_MERCHANT_KEY, PAYU_SALT, payu.in URLs, code calling /_payment, bolt.payu.in script, or computing hashes with `key|txnid|amount|...`).

Migration playbook for moving an existing integration from Razorpay Payment Gateway to Paytm Payment Gateway. Covers per-flow API mapping (orders, payments, webhooks, refunds, subscriptions, links, QR), field-name translation, signature scheme differences (Razorpay HMAC-SHA256 over pipe-joined string vs Paytm's checksum library), dual-write rollout pattern, reconciliation, and cutover. Load this skill when the user mentions migrating, switching, or moving from Razorpay to Paytm, or has an existing Razorpay integration in the codebase (e.g. `razorpay` in package.json / requirements.txt / pom.xml, `rzp_live_*` / `rzp_test_*` keys, code calling `razorpay.orders.create()`, `razorpay.payments.fetch()`, `validateWebhookSignature`, etc.).

Paytm refunds - full and partial refunds against a successful order. Covers `POST /refund/apply`, `POST /v2/refund/status`, refund webhooks, the `refId` uniqueness rule, partial-refund cumulative limit, PENDING-state behavior (bank delays up to T+7 working days), and the dispute/chargeback relationship. Load when the user asks about refunding a payment, partial refund, refund status, or "money back". Returns may take days; do NOT confuse refund PENDING with payment PENDING.

Server-to-server (S2S) webhook receiver for Paytm payment events - the source of truth that outlives lost browser callbacks. Covers: raw-body extraction (re-serializing breaks the signature), signature verification against `head.signature`, dedup on `(orderId, status)` for at-least-once delivery, the 200/401/5xx response contract that controls Paytm retries, and a reference handler stub. Load this skill when the user mentions "webhook", "S2S notification", "callback (server-side)", "fulfilment hook", or "signature verification" in a Paytm context.

Paytm Custom SDK for native Android and iOS apps where the merchant builds their own payment UI and uses the SDK only as a thin client to Paytm's APIs (fetch payment options, generate instrument tokens, submit a payment, get status). Use this when the user wants their app's branding / UX on the payment screen instead of Paytm's default. More work than All-in-One, more flexibility. Do NOT use when the user just wants the fastest mobile checkout - load `all-in-one-sdk` instead.

First-step setup for Paytm Payment Gateway: where to get MID + Merchant Key (staging vs prod), staging-vs-prod environment URLs, .env / .env.example conventions, dashboard access, and the decision tree for picking the right Paytm flow (one-time payment vs subscription vs payment link vs dynamic QR). Load this skill whenever the user is starting a fresh Paytm integration, asking about credentials/environments/dashboard, or unsure which Paytm product fits their use case.

Paytm All-in-One SDK for native Android and iOS apps. The fastest mobile integration - the SDK renders the full Paytm payment UI (UPI, Credit Cards, Debit Cards, Net Banking, EMI) inside your app, handles all payment instruments, and returns a single result callback. Use this when the user wants a turn-key mobile checkout with the standard Paytm look and feel. Do NOT use for custom-branded payment screens - load `custom-sdk` instead.

Paytm Payment Links - server-only flow that returns a `shortUrl` you share via SMS / WhatsApp / email. Paytm hosts the checkout page, so there is NO frontend / JS Checkout work. Covers `/link/create`, `/link/fetch`, `/link/update`, `/link/resendNotification`, `/link/expire`, and `/link/fetchTransaction` for reconciliation. Includes the MID-specific quirks that bite hardest: `linkId` as JSON number (NOT string), `linkName` charset (alphanumerics ONLY, no spaces), dual-shape `isActive` vs `linkStatus` responses, dual-shape `SUCCESS` vs `TXN_SUCCESS` order status, and the AES head shape vs the order-status API. Load this skill for "shareable link", "invoice link", "payment link via SMS / WhatsApp / email".

Paytm Dynamic QR (DQR) for in-store / counter / table-side / printed payments. Server-only flow: POST `/paymentservices/qr/create`, render the returned image (base64 PNG) or `qrData` (UPI deep link) on a screen or print it. Customer scans with any UPI app and pays. NO JS Checkout. Covers the required `posId`, the base64-image prefix gotcha, and post-payment polling. Load this skill for "QR code", "scan to pay", "in-store", "counter", "table-side", "print QR".