📦 Paytm 集成技能

Paytm Payment Gateway 集成技能概览 Paytm Payment Gateway 支持 UPI、信用卡/借记卡、网银、EMI。 本技能支持的集成方式：JS Checkout（网页）、Subscriptions / UPI Autopay、Payment Links、Dynamic QR Codes —— 全部基于 Server-to-Server API。

关键概念 概念 | 说明 MID | Merchant ID —— Paytm 账户唯一标识 Merchant Key | 用于生成/校验 checksum 的密钥 txnToken | Initiate Transaction API 返回的短时令牌，后续步骤均需使用 CHECKSUMHASH | 用 Merchant Key 生成的 HMAC-SHA256 签名，用于校验 API 请求 ORDER_ID | 商户生成的每笔交易唯一标识 callbackUrl | 支付完成后 Paytm POST 结果给商户的地址

环境 环境 | Base URL（新 MID 默认） | 旧主机 Staging | https://securestage.paytmpayments.com | https://securegw-stage.paytm.in Production | https://secure.paytmpayments.com | https://securegw.paytm.in 新商户默认分配到 paytmpayments.com；旧 MID 可能仍解析到 paytm.in。以 dashboard 显示的为准，两者按 MID 不可混用。务必先在 staging 构建并测试。

核心集成流程 ⚡ 先选对流程（写代码前必读） 把用户意图映射到以下 4 种流程之一，选错会产出“能用但方向错误”的代码 —— 是本技能最昂贵的一类 bug。

用户说… | 流程 | 端点 | 需 JS Checkout？ | 参考 “checkout page”“pay button on website”“one-time payment”“buy” | Payment | POST /theia/api/v1/initiateTransaction (requestType: "Payment") | ✅ 是 | references/js-checkout.md “subscription”“monthly”“auto-debit”“mandate”等 | Subscription | POST /subscription/create (requestType: "NATIVE_SUBSCRIPTION") | ✅ 是（用于授权页） | references/subscriptions.md ← 必读 “shareable link”“invoice link” | Payment Link | POST /link/create | ❌ 否 —— Paytm 托管页面 | references/payment-links.md “QR code”“scan to pay” | Dynamic QR | POST /paymentservices/qr/create | ❌ 否 —— 渲染二维码，顾客用 UPI App 扫 | references/qr-codes.md

以下步骤仅描述 Payment + JS Checkout，请勿套用到其余三种流程 —— 它们的端点、请求结构、校验规则均不同。请打开对应参考文件并按其流程执行。

高频致命错误

• Subscription：端点是 /subscription/create（非 initiateTransaction），requestType 是 NATIVE_SUBSCRIPTION（非 SUBSCRIPTION 或 Payment），subscription 字段直接放 body 顶层，无 subscriptionDetails 包裹。
• Payment Link：fetch / update / resend / expire 的标识是 linkId（JSON number，非 string）；resend 路径为 /link/resendNotification（非 /link/resend）。
• Dynamic QR：posId 必填（缺则 400）；amount 为带两位小数的字符串。

Step 1 – 生成 Checksum（服务端） 所有 API 请求头须带 CHECKSUMHASH 作为签名。 使用 Paytm 官方 checksum 库（Java、PHP、Python、Node.js、.NET、Go）： Docs: https://www.paytmpayments.com/docs/checksum/ GitHub: https://github.com/Paytm-Payments

# Python 示例 from paytmchecksum import PaytmChecksum checksum = PaytmChecksum.generateSignature(json.dumps(body), MERCHANT_KEY)

// Java 示例 String checksum = PaytmChecksum.generateSignature(body.toString(), MERCHANT_KEY);

收到支付回调后，务必先在校验通过后再信任数据： is_valid = PaytmChecksum.verifySignature(response_body, MERCHANT_KEY, checksumhash)

Step 2 – Initiate Transaction API 服务端调用，先获取 txnToken 再渲染支付 UI。 端点：POST {BASE_URL}/theia/api/v1/initiateTransaction?mid={MID}&orderId={ORDER_ID}

一次性支付请求体（顶层字段均必填）： { "head": { "signature": "" }, "body": { "requestType": "Payment", "mid": "YOUR_MID", "websiteName": "YOUR_WEBSITE_NAME", "orderId": "ORD_ABC123", "callbackUrl": "https://yoursite.com/paytm/callback", "txnAmount": { "value": "1.00", "currency": "INR" }, "userInfo": { "custId": "CUST_001", "mobile": "9999999999", "email": "buyer@example.com" } } }

如需订阅/周期扣款，请勿使用上述端点及报文。 订阅需调用 /subscription/create，requestType 为 "NATIVE_SUBSCRIPTION"，字段平铺于 body 内（无 subscriptionDetails 包裹）。