Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 2: Indian Payment Gateways & UPI Webhooks6 min readVerified

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.

TL;DR — Immediate Production Fix

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.

paytm-initiate-transaction.ts
typescript
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.

app/api/webhooks/paytm/route.ts
typescript
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.

paytm-order-status-verify.ts
typescript
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()`.
India's First & Only Developer PaaS

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'`.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →