Indian-kyc-validator

Validate Indian KYC identifiers — PAN, GSTIN, IFSC, phone numbers, and Aadhaar — with real checksum logic, not just regex pattern matching.

Why this exists

Most "Indian ID validators" on npm only check format with a regex. That catches typos but not fake or fabricated IDs. This package implements the actual checksum algorithms where they're public:

• GSTIN — verified against the real modulo-36 check-digit algorithm, plus validates the embedded PAN
• PAN — structure and entity-type validation (4th character maps to Individual, Company, Trust, etc.)
• IFSC — RBI bank/branch code structure validation
• Phone — Indian mobile number rules (10 digits, starts with 6–9)
• Aadhaar — format validation only (see note below on why)

Install

npm install indian-kyc-validator

Quick start

import { isValidPAN, isValidGSTIN, isValidIFSC, isValidPhone, isValidAadhaarFormat } from 'indian-kyc-validator';

isValidPAN('ABCPD1234E');
// { valid: true, entityType: 'Individual' }

isValidGSTIN('27AAACT2727Q1ZW');
// { valid: true, panPortion: 'AAACT2727Q', stateCode: '27' }

isValidIFSC('SBIN0001234');
// { valid: true, bankCode: 'SBIN', branchCode: '001234' }

isValidPhone('+91 98765-43210');
// { valid: true }

isValidAadhaarFormat('234567890123');
// { valid: true }

Every validator returns { valid: boolean, reason?: string } so you can surface a clear error message to users on failure:

isValidGSTIN('27AAACT2727Q1ZX');
// { valid: false, reason: "Checksum mismatch: expected 'W', got 'X'" }

API reference

isValidPAN(pan: string): PANValidationResult

Validates structure (AAAAA9999A) and resolves the entity type from the 4th character.

| Field | Type | Description | |---|---|---| | valid | boolean | Whether the PAN passed validation | | entityType | string? | Individual, Company, HUF, Trust, Partnership Firm, AOP, BOI, Local Authority, Artificial Judicial Person, or Government | | reason | string? | Present only when valid is false |

isValidGSTIN(gstin: string): GSTINValidationResult

Validates structure, state code, embedded PAN, and the modulo-36 check digit.

| Field | Type | Description | |---|---|---| | valid | boolean | Whether the GSTIN passed all checks | | stateCode | string? | 2-digit state code (e.g. '27' = Maharashtra) | | panPortion | string? | The PAN embedded in characters 3–12 | | reason | string? | Present only when valid is false |

isValidIFSC(ifsc: string): IFSCValidationResult

Validates the 11-character RBI bank branch code structure.

| Field | Type | Description | |---|---|---| | valid | boolean | Whether the IFSC passed validation | | bankCode | string? | First 4 characters | | branchCode | string? | Last 6 characters |

isValidPhone(phone: string): ValidationResult

Validates Indian mobile numbers. Accepts optional +91, 91, or 0 prefix, and strips spaces/hyphens automatically.

isValidAadhaarFormat(aadhaar: string): ValidationResult

Validates the 12-digit structure (first digit cannot be 0 or 1).

Note on Aadhaar: this is format validation only, not real verification. Aadhaar numbers use a Verhoeff checksum, but UIDAI hasn't publicly documented the implementation for third-party use, and actual Aadhaar verification is legally restricted to UIDAI-authorized entities under the Aadhaar Act, 2016. Use this to catch obviously malformed input before submitting to an authorized verification service — not as proof the number is real.

Edge cases handled

| Case | Behavior | |---|---| | Lowercase input | Normalized to uppercase before validation | | Extra whitespace | Trimmed automatically | | Phone with +91/0 prefix | Prefix stripped, remaining 10 digits validated | | GSTIN with valid format but wrong checksum | Rejected with the expected vs. actual check digit in reason | | GSTIN with invalid embedded PAN | Rejected, even if the GSTIN's own structure looks correct | | Non-string input (null, number, etc.) | Returns { valid: false } instead of throwing |

Disclaimer

This package validates the structure and checksum of these identifiers. It does not confirm that an ID belongs to a real, registered person or entity, and is not a substitute for official KYC verification through UIDAI, the Income Tax Department, GSTN, or RBI systems. Always verify with the relevant government API for anything compliance-critical.

License

MIT