| name | paytm-migrate-from-cashfree |
| description | 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`).
|
| triggers | ["cashfree","Cashfree","cashfree-pg","cashfree-pg-sdk-nodejs","cashfree-pg-sdk-python","cashfreepayments.com","api.cashfree.com","sandbox.cashfree.com","CASHFREE_APP_ID","CASHFREE_SECRET_KEY","Cashfree.PG.Orders","Cashfree.PGCreateOrder","payment_session_id","cf_order_id","cf_payment_id","/pg/orders","x-client-id","x-client-secret","migrate from cashfree","migrating from cashfree","migration from cashfree","cashfree to paytm","cashfree → paytm","cashfree -> paytm","from cashfree to paytm","switch from cashfree","switching from cashfree","move from cashfree","moving from cashfree","port from cashfree","shift from cashfree","transition from cashfree","swap cashfree","swap out cashfree","replace cashfree","replacing cashfree","remove cashfree","drop cashfree","ditch cashfree","leave cashfree","exit cashfree","retire cashfree","phase out cashfree","decommission cashfree","cutover from cashfree","want to use paytm instead of cashfree","thinking of switching from cashfree","considering paytm over cashfree","cashfree alternative","alternative to cashfree","instead of cashfree","unhappy with cashfree","cashfree not working for us","cashfree is expensive","cashfree account suspended","cashfree settlement delay","cashfree support bad","change payment gateway from cashfree","change pg from cashfree","stop using cashfree","get rid of cashfree","dual write cashfree paytm"] |
Cashfree → Paytm Migration
Use this skill when a merchant has a working Cashfree Payments integration and wants to switch to Paytm. Covers the API mental-model translation, signature scheme differences, recurring payments, refunds, dual-write rollout, and cutover.
This skill is split across two files. SKILL.md (this file) gives the at-a-glance mapping + per-flow summary. references/REFERENCE.md contains the full Cashfree product surface (PG / Subscriptions / Payment Links / Easy Split / Payouts / Auto-collect — what migrates and what doesn't), the per-endpoint diff with code samples, header-auth vs body-checksum deep dive, subscription field/frequency mapping, webhook signature scheme (timestamp + rawBody HMAC vs Paytm checksum), dual-write tweaks for header-based auth, and 90-day cutover checklist — all NOT repeated here.
Do not generate any Cashfree → Paytm migration code until you have read references/REFERENCE.md.
At a glance
| Concept | Cashfree | Paytm |
|---|
| Identifier | X-Client-Id + X-Client-Secret (app id + secret key) | MID + MERCHANT_KEY |
| Order create | POST /pg/orders (returns payment_session_id) | POST /theia/api/v1/initiateTransaction (returns txnToken) |
| Auth on each request | Two HTTP headers: x-client-id, x-client-secret, x-api-version | Body checksum in head.signature |
| Browser checkout | Cashfree({ mode }).checkout({ paymentSessionId, ... }) | Paytm.CheckoutJS.init({ ... }).then(invoke) |
| Webhook signature | x-webhook-signature header — HMAC-SHA256 of timestamp + rawBody with secret key, base64-encoded | head.signature field in body — PaytmChecksum.verifySignature(rawBody, KEY, sig) |
| Refund | POST /pg/orders/{order_id}/refunds | POST /refund/apply |
| Subscription | Cashfree Subscriptions API (POST /pg/subscriptions) | POST /subscription/create (NATIVE_SUBSCRIPTION, flat body) |
| Source of truth | GET /pg/orders/{order_id} + GET /pg/orders/{order_id}/payments | POST /v3/order/status |
Critical mental shift: Cashfree's auth is two custom HTTP headers per request. Paytm's auth is a body checksum field. Reusing Cashfree's x-client-secret header against Paytm endpoints does nothing (Paytm ignores the headers) and the request fails with checksum mismatches that look unrelated.
Second mental shift: Cashfree exposes an explicit API version via x-api-version (e.g. 2022-09-01, 2023-08-01). Paytm has no equivalent — its endpoints version implicitly. Drop the version-header concept entirely when porting.
Migration paths (pick one)
| User situation | Recommended path | Reference section |
|---|
| Greenfield rewrite | Cutover — replace Cashfree pg/orders + cashfree.checkout() with Paytm REST + JS Checkout | REFERENCE.md § Direct cutover |
| Production traffic | Dual-write canary — sticky-hash by customer; both gateways live; % traffic to Paytm | REFERENCE.md § Dual-write |
| Cashfree-specific features (Easy Split, Payouts) | Partial migration — switch PG flows, keep Cashfree for Split / Payouts long-term | REFERENCE.md § Permanent multi-PSP |
Reference dual-write implementation (generic): scripts/backend-{node,python,spring,spring-legacy}/razorpay-migration/. Adapt by swapping the source-PSP branch for Cashfree's Cashfree.PG.Orders.CreateOrder().
Per-flow mapping (high level)
Each row corresponds to a focused mapping section in references/REFERENCE.md.
One-time payments (cards, UPI, NB, EMI)
Cashfree Paytm
──────── ─────
1. POST /pg/orders → POST /theia/api/v1/initiateTransaction
headers: x-client-id, x-client-secret, body checksum in head.signature
x-api-version
body: { order_id, order_amount, order_currency,
customer_details, order_meta }
returns: { payment_session_id, order_id, ... } returns: { body: { txnToken, resultInfo } }
2. Frontend: cashfree.checkout({ → Paytm.CheckoutJS.init({ data: { token: txnToken, ... } })
paymentSessionId, redirectTarget: "_self" }) .then(() => Paytm.CheckoutJS.invoke())
3. Verify: GET /pg/orders/:order_id → POST /v3/order/status
pull order_status + payment_status body.resultInfo.resultStatus
→ Load the js-checkout skill alongside.
Subscriptions
Cashfree Paytm
──────── ─────
1. POST /pg/subscriptions → POST /subscription/create
creates a Subscription with Plan id requestType: "NATIVE_SUBSCRIPTION"
FLAT body (no subscriptionDetails wrapper)
head: { clientId, channelId, signature }
2. Frontend: cashfree.subscribe({...}) → Same Paytm.CheckoutJS modal as one-time payment
3. Cashfree auto-debits per cycle → Paytm auto-debits per cycle
4. Webhook per cycle: SUBSCRIPTION_PAYMENT → Webhook: txnType: "SUBSCRIPTION_DEBIT"
5. Cancel: POST /pg/subscriptions/:id/cancel → POST /subscription/cancel
→ Load the subscriptions skill alongside.
Refunds
Cashfree Paytm
──────── ─────
POST /pg/orders/:order_id/refunds → POST /refund/apply
{ refund_amount, refund_id, refund_note } { body: { txnType: "REFUND", orderId, txnId,
refId, refundAmount } }
GET /pg/orders/:order_id/refunds/:refund_id → POST /v2/refund/status
Refund webhook Same /paytm/webhook endpoint, txnType: "REFUND"
→ Load the refunds skill alongside.
Webhooks
Cashfree Paytm
──────── ─────
HTTP POST { type, data, event_time } → HTTP POST { head: { signature }, body: { ... } }
Headers:
x-webhook-signature: <base64-HMAC-SHA256(timestamp+rawBody, secret)>
x-webhook-timestamp: <epoch_seconds>
x-webhook-version: <api-version>
Verify: HMAC over (timestamp + rawBody) Verify: PaytmChecksum.verifySignature(rawBody, KEY, sig)
compare base64-encoded result using the merchant key
to header
Event types: body.txnType distinguishes:
PAYMENT_SUCCESS_WEBHOOK_V2 "SALE" - one-time payment
PAYMENT_FAILED_WEBHOOK_V2 "REFUND"
REFUND_STATUS_WEBHOOK "SUBSCRIPTION_DEBIT" / "SUBSCRIPTION_CANCEL"
SUBSCRIPTION_PAYMENT_WEBHOOK
→ Load the webhooks skill alongside.
Signature scheme — the highest-confusion area
Cashfree: API requests use two HTTP headers (x-client-id and x-client-secret). Webhooks use a separate scheme: HMAC-SHA256(timestamp + rawBody, secretKey) → base64-encoded, sent as x-webhook-signature header. The webhook timestamp is in x-webhook-timestamp.
Paytm: every API request body carries a head.signature field — checksum of the JSON-stringified body using MERCHANT_KEY. The Paytm checksum library handles both sides. No HTTP custom headers for auth. No timestamp prepending for webhooks.
Common bug when porting: developers reuse Cashfree's crypto.createHmac("sha256", secret).update(timestamp + body) against Paytm webhooks. Paytm rejects with checksum mismatch because (a) signature goes inside body not header, (b) no timestamp prepended, (c) verification must use the official library.
✅ Final step — codebase cleanup scan (mandatory, do not skip)
After all functional code is migrated, run this scan to catch non-functional Cashfree references that survive every "complete" migration:
grep -rn \
--include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" \
--include="*.html" --include="*.json" --include="*.md" \
--include="*.env*" --include="*.yaml" --include="*.yml" \
"cashfree\|Cashfree\|CASHFREE\|cf_order_id\|cf_payment_id\|payment_session_id\|x-client-id" \
. 2>/dev/null
Common survivors:
| File / Surface | What to replace |
|---|
| HTML / JSX footer & copy | "Secured by Cashfree Payments" → "Secured by Paytm" |
package.json description field | Remove "Cashfree" mention |
.env.example placeholders | CASHFREE_APP_ID=... → PAYTM_MID=... |
README.md / docs | Setup steps, screenshots, badges |
| Code comments | // Cashfree session id / // x-client-secret header |
| UI labels / modal titles | "Cashfree Checkout" → product name |
| Test fixtures | Hardcoded sandbox app IDs / order tokens |
| Translation files (i18n) | payment.gateway.cashfree keys |
| CI / deploy configs | Lingering env-var names |
If any survive after the grep, ship a follow-up commit before declaring the migration complete.
When to load related skills
This skill is the migration translator. Always pair with the matching flow skill:
- One-time payment → also load
js-checkout
- Subscription → also load
subscriptions
- Payment link → also load
payment-links (Cashfree's "Payment Links" map cleanly)
- Refund → also load
refunds
- Webhook → also load
webhooks
- Mobile SDK → also load
all-in-one-sdk or custom-sdk
- Errors during migration →
troubleshooting
