Resolving Paytm Error Code 330 (Checksum Mismatch) in Initiate Transaction & Webhooks
Fix Paytm Payment Gateway RespCode 330 (Paytm Checksum Mismatch) in Node.js and Next.js. Understand JSON.stringify(body) vs key-value Map signing in paytmchecksum for v1/initiateTransaction and webhooks.
Paytm Payment Gateway returns `RespCode: 330` (`Paytm checksum mismatch` / `Invalid Checksum`) whenever the AES-128-CBC + SHA-256 signature generated by `PaytmChecksum.generateSignature()` does not match the payload received by Paytm's servers. In 90% of Node.js and Next.js integrations, this happens because developers pass a JavaScript Object (`paytmParams.body`) to `generateSignature()` when calling the v2 JSON API (`/theia/api/v1/initiateTransaction`), whereas the v2 API strictly requires passing the exact serialized JSON string (`JSON.stringify(paytmParams.body)`). Conversely, Paytm's legacy `application/x-www-form-urlencoded` webhook callback requires passing the flat parameter object (with `CHECKSUMHASH` deleted first) into `verifySignature()`.
Verified Root Causes in Production Environments
- Passing an Object Instead of JSON.stringify(body) on v2 APIs: In Paytm's `/theia/api/v1/initiateTransaction` API, `PaytmChecksum.generateSignature(JSON.stringify(body), MERCHANT_KEY)` hashes the exact JSON string, whereas passing `body` as an Object sorts keys with `|` pipe delimiters (v1 mode), causing an immediate 330 error.
- Trailing Whitespace or Hidden Newlines in MERCHANT_KEY: Copying the 16-character or 32-character Merchant Key from the Paytm Developer Dashboard with a trailing space corrupts the AES encryption key.
- Not Removing CHECKSUMHASH Before Verifying Form-Encoded Webhooks: When verifying a flat `application/x-www-form-urlencoded` callback payload, leaving `CHECKSUMHASH` inside the parameter dictionary invalidates verification.
1. Why Paytm RespCode 330 Happens: String Mode vs Object Map Mode in paytmchecksum
The official `paytmchecksum` npm package exposes a single polymorphic function: `PaytmChecksum.generateSignature(params, key)`. If `typeof params === 'string'`, it computes a 4-character random salt, appends it to the raw JSON string, hashes it with SHA-256, and encrypts the digest using AES-128-CBC (`iv = '@@@@&&&&####$$$$'`). However, if `typeof params === 'object'`, it sorts the object keys alphabetically and joins their values with `|` pipes before hashing.
Paytm's modern Custom Checkout and JS Checkout APIs (`/theia/api/v1/initiateTransaction`, `/v3/order/status`, and `/v2/refund/apply`) expect a JSON structure `{ "body": { ... }, "head": { "signature": "..." } }`. For all of these endpoints, you MUST pass `JSON.stringify(paytmParams.body)` (a string) into `generateSignature`, and send that exact same serialized string over the wire.
import PaytmChecksum from 'paytmchecksum';
export async function createPaytmTransactionToken({
orderId,
amountInr,
customerId,
}: {
orderId: string;
amountInr: number;
customerId: string;
}) {
const mid = process.env.PAYTM_MID!.trim();
const merchantKey = process.env.PAYTM_MERCHANT_KEY!.trim();
const websiteName = process.env.PAYTM_WEBSITE || 'DEFAULT'; // 'WEBSTAGING' in sandbox
const bodyObj = {
requestType: 'Payment',
mid,
websiteName,
orderId,
callbackUrl: `https://vexlo.cloud/api/webhooks/paytm`,
txnAmount: {
// Paytm requires exact 2-decimal string (e.g. "149.00")
value: Number(amountInr).toFixed(2),
currency: 'INR',
},
userInfo: {
custId: customerId,
},
};
// CRITICAL: Serialize bodyObj to a JSON string BEFORE signing!
const bodyJsonString = JSON.stringify(bodyObj);
const checksum = await PaytmChecksum.generateSignature(bodyJsonString, merchantKey);
const requestPayload = JSON.stringify({
body: bodyObj,
head: {
signature: checksum,
},
});
const baseUrl =
process.env.PAYTM_ENV === 'production'
? 'https://securegw.paytm.in'
: 'https://securegw-stage.paytm.in';
const res = await fetch(
`${baseUrl}/theia/api/v1/initiateTransaction?mid=${mid}&orderId=${orderId}`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: requestPayload,
}
);
return res.json();
}2. Verifying Paytm Webhook & Callback Payloads in Next.js App Router
When a customer completes a UPI or RuPay payment on Paytm, Paytm can notify your server in two formats: (A) the browser/S2S `callbackUrl` (`application/x-www-form-urlencoded` containing flat key-value pairs including `CHECKSUMHASH`), or (B) a JSON v2 webhook containing `{ "body": { ... }, "head": { "signature": "..." } }`.
Your Next.js App Router handler must inspect the `Content-Type` header to choose the matching verification mode—passing a cloned object (with `CHECKSUMHASH` deleted) for form-encoded callbacks, or `JSON.stringify(payload.body)` for JSON webhooks.
import { NextRequest, NextResponse } from 'next/server';
import PaytmChecksum from 'paytmchecksum';
export const runtime = 'nodejs';
export async function POST(req: NextRequest) {
const merchantKey = process.env.PAYTM_MERCHANT_KEY!.trim();
const contentType = req.headers.get('content-type') || '';
if (contentType.includes('application/x-www-form-urlencoded')) {
const formData = await req.formData();
const params: Record<string, string> = {};
let checksumHash = '';
formData.forEach((value, key) => {
if (key === 'CHECKSUMHASH') {
checksumHash = String(value);
} else {
params[key] = String(value);
}
});
// Form-encoded callbacks use Object Map mode (params object without CHECKSUMHASH)
const isValid = PaytmChecksum.verifySignature(params, merchantKey, checksumHash);
if (!isValid) {
return NextResponse.json({ error: 'RespCode 330: Checksum mismatch' }, { status: 401 });
}
return NextResponse.json({ status: 'verified', orderId: params.ORDERID, txnStatus: params.STATUS });
}
// JSON Webhook Mode ({ head: { signature }, body: { ... } })
const jsonPayload = await req.json();
const signature = jsonPayload?.head?.signature;
const bodyString = JSON.stringify(jsonPayload?.body || {});
const isValidJson = PaytmChecksum.verifySignature(bodyString, merchantKey, signature);
if (!isValidJson) {
return NextResponse.json({ error: 'RespCode 330: JSON signature mismatch' }, { status: 401 });
}
return NextResponse.json({ status: 'verified', orderId: jsonPayload.body.orderId });
}3. Secondary Causes of Paytm Error 330: Staging vs Production MIDs & Amount Formatting
Even when your `JSON.stringify(body)` call is syntactically correct, Paytm will return `resultCode: "330"` if you mix Staging credentials (`securegw-stage.paytm.in` with `WEBSTAGING`) and Production credentials (`securegw.paytm.in` with `DEFAULT`). Additionally, always format `txnAmount.value` as a two-decimal string (`"149.00"`) rather than a raw number (`149`) so JSON serialization never alters decimal precision between checksum creation and HTTP transport.
import PaytmChecksum from 'paytmchecksum';
// Always double-verify TXN_SUCCESS via Paytm v3 Order Status API
export async function checkPaytmOrderStatus(mid: string, orderId: string, merchantKey: string) {
const bodyObj = { mid, orderId };
const signature = await PaytmChecksum.generateSignature(JSON.stringify(bodyObj), merchantKey);
const res = await fetch('https://securegw.paytm.in/v3/order/status', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ body: bodyObj, head: { signature } }),
});
return res.json();
}Pre-Deployment Verification Checklist
- Pass `JSON.stringify(bodyObj)` (a String, NOT an Object) to `PaytmChecksum.generateSignature()` for all `/theia/api/v1/*` and `/v3/order/status` endpoints.
- Call `.trim()` on `PAYTM_MID` and `PAYTM_MERCHANT_KEY` to eliminate hidden newline or space characters from `.env` files.
- Format `txnAmount.value` as an exact 2-decimal string (`"149.00"`).
- Delete `CHECKSUMHASH` from the parameter object before passing form-encoded callback fields to `PaytmChecksum.verifySignature()`.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does Paytm return RespCode 330 Invalid Checksum even when my Merchant Key is correct?
You are likely passing the `body` JavaScript Object directly into `PaytmChecksum.generateSignature(body, key)` instead of `PaytmChecksum.generateSignature(JSON.stringify(body), key)`. Paytm's v2 JSON APIs hash the raw JSON string, whereas passing an Object hashes pipe-separated key values.
What websiteName should I use for Paytm Staging vs Production?
Use `WEBSTAGING` when calling `https://securegw-stage.paytm.in` with test credentials, and `DEFAULT` (or the custom website string assigned in your Paytm Merchant Dashboard) when calling `https://securegw.paytm.in` in production.
Is a Paytm callback verification enough to fulfill an order?
No. Paytm's official integration security guidelines require verifying the checksum on the callback AND making a server-to-server POST call to `/v3/order/status` to confirm `resultInfo.resultStatus === 'TXN_SUCCESS'`.