upi-validator

Zero-dependency, ultra-fast Indian UPI ID (VPA) validator, bank handle recognizer, and NPCI upi://pay deep link intent URL builder & parser for Node.js, browsers, and Edge runtimes.

---

🚀 Features

• ⚡ Zero Dependencies: Pure TypeScript implementation with zero external runtime packages.
• 🎯 NPCI Compliance: Full validation of Indian Unified Payments Interface (UPI) VPA specifications (length limits, character sets, separators).
• 🏦 170+ Official Handles: Extensive registry of NPCI-approved bank and PSP handles (Google Pay, PhonePe, Paytm, BHIM, CRED, Amazon Pay, SBI, HDFC, ICICI, Axis, Kotak, RRBs, SFBs).
• 🔗 NPCI Intent Deep Links: Create and parse official upi://pay deep links with query parameters (pa, pn, am, cu, tn, tr, mc, url, sign).
• 📦 Dual ESM & CommonJS: Ships with complete ES module and CommonJS distributions with .d.ts declaration maps.
• 🛡️ Type-Safe: 100% strict TypeScript typing out of the box.

---

📦 Installation

# npm
npm install upi-validator

# yarn
yarn add upi-validator

# pnpm
pnpm add upi-validator

---

⚡ Quick Start

1. Validate UPI ID (VPA) & Recognize Bank / PSP

import { validateUpiId, isValidUpiId } from "upi-validator";

// Comprehensive validation result
const result = validateUpiId("rahul.sharma@okaxis");
console.log(result);
/*
{
  isValid: true,
  vpa: "rahul.sharma@okaxis",
  username: "rahul.sharma",
  handle: "okaxis",
  provider: "Google Pay",
  isKnownHandle: true
}
*/

// Fast boolean check
if (isValidUpiId("9876543210@paytm")) {
  console.log("Valid UPI ID!");
}

2. Generate NPCI Intent URL (upi://pay)

Generate standard deep links for QR codes, payment buttons, and mobile app intents:

import { buildUpiIntentUri } from "upi-validator";

const intentUri = buildUpiIntentUri({
  pa: "merchant@okhdfcbank",
  pn: "Acme Retail Store",
  am: 1249.50,
  tn: "Order #84920",
  tr: "TXN84920",
  cu: "INR",
});

console.log(intentUri);
// upi://pay?pa=merchant%40okhdfcbank&pn=Acme%20Retail%20Store&am=1249.50&cu=INR&tn=Order%20%2384920&tr=TXN84920

3. Parse and Validate UPI Deep Links

Extract payment parameters from incoming deep links or scanned QR strings:

import { parseUpiIntentUri } from "upi-validator";

const data = parseUpiIntentUri("upi://pay?pa=seller@ybl&pn=Coffee%20House&am=150.00&cu=INR");

console.log(data.pa); // "seller@ybl"
console.log(data.pn); // "Coffee House"
console.log(data.am); // 150
console.log(data.validationResult.provider); // "PhonePe"

---

📖 API Reference

validateUpiId(vpa: unknown): UpiValidationResult

Validates structure, characters, length, and checks against the registry of registered NPCI bank and PSP handles.

interface UpiValidationResult {
  isValid: boolean;
  vpa: string;
  username: string;
  handle: string;
  provider?: string;
  isKnownHandle: boolean;
  error?: string;
}

Validation Rules:

• Length: 3 to 255 total characters.
• Separator: Exactly one @ symbol.
• Username (username@...):
  • 1 to 100 characters.
  • Allowed characters: alphanumeric (a-z, 0-9), dot (.), hyphen (-), underscore (_).
  • Cannot begin or end with a special character.
  • Cannot contain consecutive special characters (.., --, __, .-).
• Handle (...@handle):
  • 2 to 64 characters.
  • Allowed characters: alphanumeric (a-z, 0-9) and dot (.).
  • Cannot be purely numeric.

---

buildUpiIntentUri(options: UpiIntentOptions): string

Constructs an NPCI-compliant upi://pay URI with validated parameters.

interface UpiIntentOptions {
  /** Payee VPA / UPI ID (Required) */
  pa: string;
  /** Payee Name (Required) */
  pn: string;
  /** Merchant Category Code (4 digits, e.g. "5411") */
  mc?: string;
  /** Transaction Reference ID */
  tr?: string;
  /** Transaction ID */
  tid?: string;
  /** Transaction Note / Description */
  tn?: string;
  /** Transaction Amount in INR (auto-formatted to 2 decimal places) */
  am?: number | string;
  /** Currency code (Defaults to "INR") */
  cu?: string;
  /** Reference URL */
  url?: string;
  /** Minimum Amount to be paid */
  mam?: number | string;
  /** Transaction Initiation Mode */
  mode?: string;
  /** Organization ID / NPCI Org ID */
  orgid?: string;
  /** Digital Signature for signed intent */
  sign?: string;
}

---

parseUpiIntentUri(uri: string): UpiIntentData

Parses query parameters from a upi://pay string and validates payee address pa.

interface UpiIntentData {
  rawUri: string;
  pa: string;
  pn: string;
  mc?: string;
  tr?: string;
  tid?: string;
  tn?: string;
  am?: number;
  amString?: string;
  cu: string;
  url?: string;
  mam?: number;
  mamString?: string;
  mode?: string;
  orgid?: string;
  sign?: string;
  otherParams: Record<string, string>;
  validationResult: UpiValidationResult;
}

---

Helper Functions

• isValidUpiId(vpa: unknown): boolean: Fast boolean check for UPI ID validity.
• getUpiHandle(vpa: string): string | null: Extracts and normalizes handle string, or returns null if invalid.
• normalizeUpiId(vpa: string): string: Normalizes valid UPI ID to lowercase string, throws if invalid.
• isKnownUpiHandle(handle: string): boolean: Checks whether a handle exists in the NPCI registry.
• getUpiProvider(handleOrVpa: string): string | undefined: Looks up provider name from handle or full VPA.
• getHandleInfo(handle: string): UpiHandleInfo | undefined: Retrieves detailed metadata for a handle.
• getAllHandles(): readonly UpiHandleInfo[]: Returns the complete registry of 170+ approved handles.
• isValidUpiIntentUri(uri: string): boolean: Validates whether a URI is a correct upi://pay intent link.

---

🏦 Supported UPI Handles (170+ Handles)

Category	Popular Handles	Provider / Sponsor
Google Pay	@okhdfcbank, @okaxis, @okicici, @oksbi, @okbizaxis	Google Pay (HDFC, Axis, ICICI, SBI)
PhonePe	@ybl, @ibl, @axl	PhonePe (YES Bank, IndusInd, Axis)
Paytm	@paytm, @ptsbi, @pthdfc, @ptaxis, @pticici	Paytm (PPBL, SBI, HDFC, Axis, ICICI)
BHIM / NPCI	@upi, @bhim	BHIM UPI (NPCI)
Amazon Pay	@apl, @rapl	Amazon Pay (Axis Bank, RBL Bank)
WhatsApp Pay	@waaxis, @wahdfcbank, @waicici, @wasbi	WhatsApp Pay
CRED	@ckers, @cbaxis, @cbsbi, @cbicici, @cbhdfc	CRED
FinTechs	@ikwik, @mbk, @slice, @jupiteraxis, @navi, @super, @postpe, @fam, @kiwi	MobiKwik, Jupiter, Slice, Navi, BharatPe
Payments Banks	@airtel, @ippb, @postbank, @jio, @fino, @nsdl	Airtel, India Post, Jio, Fino, NSDL
Public Sector Banks	@sbi, @pnb, @bob, @canbank, @cnrb, @uboi, @boi, @indianbank, @cbi, @iob, @uco, @mahb, @psb, @idbi	SBI, PNB, BOB, Canara, Union, BOI, etc.
Private Sector Banks	@hdfcbank, @icici, @axisbank, @kotak, @indus, @federal, @yesbank, @rbl, @idfcbank, @sc, @hsbc, @dbs	HDFC, ICICI, Axis, Kotak, Federal, etc.
Small Finance Banks	@aubank, @equitas, @ujjivan, @suryoday, @jana, @utkarsh, @csfb, @esaf	AU SFB, Equitas, Ujjivan, Utkarsh, etc.
Co-operative Banks	@saraswatbank, @cosmos, @svc, @tjsb, @nkgsb, @abhyudaya, @apna, @kalupurbank	Saraswat, Cosmos, SVC, TJSB, etc.
Gramin / RRB Banks	@bggb, @kgb, @kgrb, @apgb, @aryavart, @prathama, @sgb, @tgb, @agvb	Kerala Gramin, Aryavart, Prathama, etc.

---

⚡ Performance

• O(1) Handle Lookups: Internal registry utilizes a pre-computed hash Map for instant O(1) handle validation.
• Zero Allocations for Simple Checks: Regular expressions are compiled once at module load.
• Validation benchmarks easily exceed 1,000,000+ operations/second on modern hardware.

---

🧪 Testing

# Run tests with vitest
npm test

# Run tests with coverage
npm run test:coverage

---

📄 License

MIT © Vijay Misal

Security note

This package validates syntax and constructs intent URLs locally. It does not verify an account, initiate payments, or guarantee transaction success.