GSTIN Validation in Python — 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 Python 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 Python:

# Reference implementation — DO NOT use in production without thorough testing
CHARSET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"


def gstin_check_character(gstin_14: str) -> str | None:
    """Compute the GSTIN check character for the first 14 characters."""
    total = 0

    for i, ch in enumerate(gstin_14.upper()):
        char_index = CHARSET.find(ch)
        if char_index == -1:
            return None  # invalid character

        product = char_index * (i + 1)
        quotient, remainder = divmod(product, 36)
        total += quotient + remainder

    mod = total % 36
    check_value = (36 - mod) % 36
    return CHARSET[check_value]


# Examples
gstin_check_character("27AAPFU0939F1Z")  # → "V"
gstin_check_character("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. Python code example

Using the isvalid-sdk Python SDK (country-specific namespace) or the requests library. Install with pip install isvalid-sdk or pip install requests.

# gstin_validator.py
import os
from isvalid_sdk import IsValidConfig, create_client

iv = create_client(IsValidConfig(api_key=os.environ["ISVALID_API_KEY"]))

# ── Validate a GSTIN ────────────────────────────────────────────────────────
# Note: "in_" because "in" is a reserved keyword in Python

result = iv.in_.gstin("27AAPFU0939F1ZV")

if not result["valid"]:
    print("Invalid GSTIN")
else:
    print(f"Valid GSTIN from {result['stateName']}")
    print(f"PAN: {result['pan']}")
    print(f"Entity type: {result['entityType']}")

# views.py (Django REST Framework)
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from gstin_validator import validate_gstin
import requests as http_requests


class InvoiceView(APIView):
    def post(self, request):
        gstin = request.data.get("gstin")
        if not gstin:
            return Response(
                {"error": "gstin is required"},
                status=status.HTTP_400_BAD_REQUEST,
            )

        try:
            result = validate_gstin(gstin)
        except http_requests.RequestException:
            return Response(
                {"error": "GSTIN validation service unavailable"},
                status=status.HTTP_502_BAD_GATEWAY,
            )

        if not result["valid"]:
            return Response(
                {"error": "Invalid GSTIN"},
                status=status.HTTP_400_BAD_REQUEST,
            )

        return Response({
            "valid": True,
            "state": result["stateName"],
            "entityType": result["entityType"],
        })

# app.py (Flask)
from flask import Flask, request, jsonify
from gstin_validator import validate_gstin

app = Flask(__name__)


@app.post("/validate-gstin")
def validate():
    data = request.get_json()

    try:
        result = validate_gstin(data["gstin"])
    except requests.RequestException:
        return jsonify(error="GSTIN validation service unavailable"), 502

    if not result["valid"]:
        return jsonify(error="Invalid GSTIN"), 400

    return jsonify(
        valid=True,
        state=result["stateName"],
        pan=result["pan"],
        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
mh = iv.in_.gstin("27AAPFU0939F1ZV")  # Maharashtra
ka = iv.in_.gstin("29AAPFU0939F1ZB")  # Karnataka

assert mh["pan"] == ka["pan"]  # True — same entity, different states

# All of these produce the same result
iv.in_.gstin("27AAPFU0939F1ZV")
iv.in_.gstin("27 aapfu0939f 1zv")
iv.in_.gstin("27-AAPFU0939F-1ZV")

def validate_gstin_safe(gstin: str) -> dict:
    try:
        return validate_gstin(gstin)
    except requests.RequestException as exc:
        # Log and decide: fail open (allow) or fail closed (reject)
        logger.error("GSTIN validation failed: %s", exc)
        return {"valid": None, "error": "validation_unavailable"}