GSTIN Validation in Node.js — Indian Tax ID Structure Explained

1. What is a GSTIN?

The Goods and Services Tax Identification Number (GSTIN) is the unique tax identifier assigned to every business registered under India's GST regime. GST registration is mandatory for businesses with an annual turnover exceeding ₹20 lakh (₹10 lakh for special category states). Every inter-state transaction, e-commerce seller, and input-tax-credit claim requires a valid GSTIN.

A GSTIN is a 15-character alphanumeric string — not a random code, but a structured identifier that encodes the state of registration, the PAN (Permanent Account Number) of the entity, an entity serial number, and a check character. For example: 27AAPFU0939F1ZV.

If your Node.js application handles Indian B2B invoicing, GST filing, or supply-chain compliance, you need to validate GSTINs — and format-checking alone will not cut it.

2. GSTIN anatomy — 15 characters decoded

Every GSTIN follows the same structure. Let's break down 27AAPFU0939F1ZV:

State codes

The first two digits identify the state or union territory. Here are some common ones:

3. The check character algorithm

The 15th character of a GSTIN is a check character computed using a mod-36 algorithm. This is similar in concept to Luhn but operates over the full alphanumeric character set (0–9, A–Z = 36 characters). The algorithm works as follows:

1. Take the first 14 characters of the GSTIN. Map each character to its position in the set 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ (0–35).
2. For each character at position i (1-indexed), multiply its code-point value by the position factor. Compute value * (i), then split the product into quotient and remainder when divided by 36.
3. Sum all the (quotient + remainder) pairs across 14 characters.
4. Compute remainder = total % 36, then the check value is (36 - remainder) % 36.
5. Map the check value back to a character (0–9 stay as digits, 10–35 become A–Z).

Here is a reference implementation in JavaScript:

// Reference implementation — DO NOT use in production without thorough testing
const CHARSET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';

function gstinCheckCharacter(gstin14) {
  let total = 0;

  for (let i = 0; i < 14; i++) {
    const charIndex = CHARSET.indexOf(gstin14[i].toUpperCase());
    if (charIndex === -1) return null; // invalid character

    const product = charIndex * (i + 1);
    const quotient = Math.floor(product / 36);
    const remainder = product % 36;
    total += quotient + remainder;
  }

  const mod = total % 36;
  const checkValue = (36 - mod) % 36;
  return CHARSET[checkValue];
}

// Example
gstinCheckCharacter('27AAPFU0939F1Z'); // → "V"
gstinCheckCharacter('29AABCT1332L1Z'); // → "1"

4. Why manual validation isn't enough

5. The right solution: one API call

Instead of implementing state-code lookups, PAN sub-validation, and the mod-36 checksum yourself, use the IsValid GSTIN API. A single GET request validates the full structure, verifies the check character, and returns parsed fields — state name, PAN, entity type, and more.

Get your free API key at isvalid.dev. The free tier includes 100 calls per day — enough for most development and low-volume production use.

Full parameter reference and response schema: GSTIN Validation API docs →

6. Node.js code example

Using the IsValid SDK (country-specific namespace) or the native fetch API.

import { createClient } from '@isvalid-dev/sdk';

const iv = createClient({ apiKey: process.env.ISVALID_API_KEY });

// ── Validate a GSTIN ────────────────────────────────────────────────────────

const result = await iv.in.gstin('27AAPFU0939F1ZV');

if (!result.valid) {
  console.log('Invalid GSTIN');
} else {
  console.log(`Valid GSTIN from ${result.stateName}`);
  console.log(`PAN: ${result.pan}`);
  console.log(`Entity type: ${result.entityType}`);
}

7. cURL example

Validate a GSTIN directly from the terminal:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/in/gstin?value=27AAPFU0939F1ZV"

Test with an invalid GSTIN (wrong check character):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/in/gstin?value=27AAPFU0939F1ZX"

Test with an invalid state code:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.isvalid.dev/v0/in/gstin?value=99AAPFU0939F1ZV"

8. Understanding the response

Response for a valid GSTIN:

{
  "valid": true,
  "gstin": "27AAPFU0939F1ZV",
  "stateCode": "27",
  "stateName": "Maharashtra",
  "pan": "AAPFU0939F",
  "entityNumber": "1",
  "entityType": "Firm",
  "checkChar": "V"
}

When the GSTIN is invalid, valid is false and the parsed fields may be absent or partial depending on which part of the structure failed validation.

9. Edge cases

// Same PAN, different states
const mh = await iv.in.gstin('27AAPFU0939F1ZV'); // Maharashtra
const ka = await iv.in.gstin('29AAPFU0939F1ZB'); // Karnataka

console.log(mh.pan === ka.pan); // true — same entity, different states

// All of these produce the same result
await iv.in.gstin('27AAPFU0939F1ZV');
await iv.in.gstin('27 aapfu0939f 1zv');
await iv.in.gstin('27-AAPFU0939F-1ZV');

async function validateGstinSafe(gstin) {
  try {
    return await iv.in.gstin(gstin);
  } catch (err) {
    // Log and decide: fail open (allow) or fail closed (reject)
    logger.error('GSTIN validation failed:', err.message);
    return { valid: null, error: 'validation_unavailable' };
  }
}