upi-qr-code-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 techpool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# UPI QR Code Generator
+
+Generate UPI payment URIs and QR codes with a pre-filled INR amount. The
+library works in Node.js and browser applications using a bundler, and ships
+with ESM, CommonJS, and TypeScript declarations.
+
+> This package generates payment requests. It does not initiate, verify, or
+> reconcile payments and never handles a payer's UPI PIN.
+
+## Features
+
+- Creates standards-shaped `upi://pay` URIs
+- Includes and validates a fixed payment amount
+- Generates PNG data URLs or SVG strings
+- Escapes payee names, notes, and references safely
+- Supports merchant transaction references and merchant category codes
+- Provides TypeScript types and works from JavaScript
+
+## Install
+
+Once published to npm:
+
+```sh
+npm install upi-qr-code-generator
+```
+
+To install the current GitHub version:
+
+```sh
+npm install github:techpool/upi-qr-code-generator
+```
+
+Node.js 20 or newer is supported.
+
+## Quick start
+
+```js
+import {
+  createUpiPaymentUri,
+  generateUpiQrDataUrl,
+} from "upi-qr-code-generator";
+
+const payment = {
+  payeeVpa: "merchant@bank",
+  payeeName: "Example Store",
+  amount: "149.00",
+  transactionRef: "ORDER-123",
+  transactionNote: "Order 123",
+};
+
+const uri = createUpiPaymentUri(payment);
+console.log(uri);
+
+const qrDataUrl = await generateUpiQrDataUrl(payment);
+
+// Browser example
+document.querySelector("img").src = qrDataUrl;
+```
+
+The generated URI looks like this:
+
+```text
+upi://pay?pa=merchant%40bank&pn=Example%20Store&am=149.00&cu=INR&tr=ORDER-123&tn=Order%20123
+```
+
+## Generate SVG
+
+```js
+import { generateUpiQrSvg } from "upi-qr-code-generator";
+
+const svg = await generateUpiQrSvg({
+  payeeVpa: "merchant@bank",
+  payeeName: "Example Store",
+  amount: "499.50",
+  transactionRef: "ORDER-456",
+});
+```
+
+In Node.js, save the returned SVG with `node:fs/promises`. A complete example
+is available in [`examples/generate-svg.mjs`](examples/generate-svg.mjs).
+
+## CommonJS
+
+```js
+const { generateUpiQrDataUrl } = require("upi-qr-code-generator");
+
+const qrDataUrl = await generateUpiQrDataUrl({
+  payeeVpa: "merchant@bank",
+  payeeName: "Example Store",
+  amount: "99.00",
+});
+```
+
+## API
+
+### `createUpiPaymentUri(payment)`
+
+Returns the encoded `upi://pay` URI.
+
+### `generateUpiQrDataUrl(payment, qrOptions?)`
+
+Returns a promise containing a PNG `data:image/png;base64,...` URL.
+
+### `generateUpiQrSvg(payment, qrOptions?)`
+
+Returns a promise containing an SVG string.
+
+### `normalizeUpiAmount(amount)`
+
+Validates a positive amount with at most two decimal places and returns an
+exact two-decimal string. It does not silently round.
+
+### Payment options
+
+| Option | Type | Required | UPI field | Description |
+| --- | --- | --- | --- | --- |
+| `payeeVpa` | `string` | Yes | `pa` | Payee UPI virtual payment address |
+| `payeeName` | `string` | Yes | `pn` | Name shown in the payer's app |
+| `amount` | `string \| number` | Yes | `am` | Positive INR amount, maximum two decimal places |
+| `transactionRef` | `string` | No | `tr` | Unique merchant reference, maximum 35 characters |
+| `transactionNote` | `string` | No | `tn` | Payment note |
+| `merchantCode` | `string` | No | `mc` | Merchant category code supplied by an acquirer |
+
+Use decimal strings such as `"149.00"` for money. JavaScript numbers are
+accepted for convenience, but values with more than two decimal places are
+rejected rather than rounded.
+
+For dynamic merchant QR codes, supply a unique `transactionRef` for each
+payment. Your acquiring bank or PSP may require additional fields or impose
+stricter rules.
+
+### QR options
+
+```ts
+{
+  errorCorrectionLevel?: "low" | "medium" | "quartile" | "high" | "L" | "M" | "Q" | "H";
+  width?: number;
+  margin?: number;
+  scale?: number;
+  color?: {
+    dark?: string;
+    light?: string;
+  };
+}
+```
+
+Defaults are a width of 512 pixels, margin of 2 modules, and error correction
+level `M`.
+
+## Payment confirmation
+
+A successful QR scan is not proof of payment. To confirm payments, use the
+status, reconciliation, or webhook APIs provided by your bank, PSP, or payment
+gateway. Match their confirmed transaction to your unique `transactionRef`.
+
+Always show the expected payee and amount in your checkout UI. The payer should
+verify those details in their UPI app before authorizing the transaction.
+
+## UPI compatibility
+
+UPI app behavior can vary. Test production QR codes with the UPI apps your
+customers use and follow the requirements supplied by your acquiring bank or
+PSP. NPCI's merchant QR interoperability circular identifies `pa` and `pn` as
+critical fields and requires `am` and `tr` for dynamic merchant QRs.
+
+- [NPCI UPI overview](https://www.npci.org.in/product/upi)
+- [NPCI merchant QR interoperability circular](https://www.npci.org.in/PDF/npci/upi/circular/2017/Circular18_BankCompliances_to_enbaleUPIMerchantecosystem_0.pdf)
+
+## Development
+
+```sh
+npm install
+npm test
+npm run typecheck
+npm run build
+```
+
+Run the complete verification suite with:
+
+```sh
+npm run check
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,133 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  UPI_PAYMENT_SCHEME: () => UPI_PAYMENT_SCHEME,
+  createUpiPaymentUri: () => createUpiPaymentUri,
+  generateUpiQrDataUrl: () => generateUpiQrDataUrl,
+  generateUpiQrSvg: () => generateUpiQrSvg,
+  normalizeUpiAmount: () => normalizeUpiAmount
+});
+module.exports = __toCommonJS(index_exports);
+var import_qrcode = __toESM(require("qrcode"), 1);
+var UPI_PAYMENT_SCHEME = "upi://pay";
+var DEFAULT_QR_OPTIONS = {
+  errorCorrectionLevel: "M",
+  width: 512,
+  margin: 2
+};
+function requiredText(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} is required`);
+  }
+  return value.trim();
+}
+function optionalText(value, field, maxLength) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} must be a non-empty string when provided`);
+  }
+  const normalized = value.trim();
+  if (maxLength !== void 0 && normalized.length > maxLength) {
+    throw new RangeError(`${field} must be at most ${maxLength} characters`);
+  }
+  return normalized;
+}
+function normalizeUpiAmount(value) {
+  if (typeof value !== "string" && typeof value !== "number") {
+    throw new TypeError("amount must be a string or number");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError("amount must be finite");
+  }
+  const candidate = String(value).trim();
+  const match = /^(0|[1-9]\d*)(?:\.(\d{1,2}))?$/.exec(candidate);
+  if (!match) {
+    throw new TypeError(
+      "amount must be a positive decimal with no more than two decimal places"
+    );
+  }
+  const whole = match[1];
+  const fraction = (match[2] ?? "").padEnd(2, "0");
+  if (BigInt(whole) === 0n && fraction === "00") {
+    throw new RangeError("amount must be greater than zero");
+  }
+  return `${whole}.${fraction}`;
+}
+function createUpiPaymentUri(options) {
+  if (options === null || typeof options !== "object") {
+    throw new TypeError("payment options are required");
+  }
+  const payeeVpa = requiredText(options.payeeVpa, "payeeVpa");
+  if (!/^[^\s@]+@[^\s@]+$/.test(payeeVpa)) {
+    throw new TypeError("payeeVpa must be a valid UPI virtual payment address");
+  }
+  const fields = [
+    ["pa", payeeVpa],
+    ["pn", requiredText(options.payeeName, "payeeName")],
+    ["am", normalizeUpiAmount(options.amount)],
+    ["cu", "INR"],
+    ["tr", optionalText(options.transactionRef, "transactionRef", 35)],
+    ["tn", optionalText(options.transactionNote, "transactionNote")],
+    ["mc", optionalText(options.merchantCode, "merchantCode")]
+  ];
+  const query = fields.filter((field) => field[1] !== void 0).map(
+    ([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
+  ).join("&");
+  return `${UPI_PAYMENT_SCHEME}?${query}`;
+}
+function generateUpiQrDataUrl(payment, qrOptions = {}) {
+  const options = {
+    ...DEFAULT_QR_OPTIONS,
+    ...qrOptions,
+    type: "image/png"
+  };
+  return import_qrcode.default.toDataURL(createUpiPaymentUri(payment), options);
+}
+function generateUpiQrSvg(payment, qrOptions = {}) {
+  const options = {
+    ...DEFAULT_QR_OPTIONS,
+    ...qrOptions,
+    type: "svg"
+  };
+  return import_qrcode.default.toString(createUpiPaymentUri(payment), options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UPI_PAYMENT_SCHEME,
+  createUpiPaymentUri,
+  generateUpiQrDataUrl,
+  generateUpiQrSvg,
+  normalizeUpiAmount
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import QRCode from \"qrcode\";\nimport type {\n  QRCodeErrorCorrectionLevel,\n  QRCodeToDataURLOptions,\n  QRCodeToStringOptions,\n} from \"qrcode\";\n\n/** Details encoded in a UPI payment QR code. */\nexport interface UpiPaymentOptions {\n  /** Payee virtual payment address, for example `merchant@bank`. */\n  payeeVpa: string;\n  /** Name displayed by the payer's UPI app. */\n  payeeName: string;\n  /** Positive INR amount with no more than two decimal places. Prefer a string. */\n  amount: string | number;\n  /** Merchant transaction reference. Dynamic merchant QRs should include this. */\n  transactionRef?: string;\n  /** Note displayed with the payment. */\n  transactionNote?: string;\n  /** Merchant category code, when supplied by the acquiring bank or PSP. */\n  merchantCode?: string;\n}\n\n/** Rendering controls shared by the PNG data URL and SVG generators. */\nexport interface UpiQrOptions {\n  /** Error-correction level. Defaults to `M`. */\n  errorCorrectionLevel?: QRCodeErrorCorrectionLevel;\n  /** Width in pixels. Defaults to 512. */\n  width?: number;\n  /** Quiet-zone width in QR modules. Defaults to 2. */\n  margin?: number;\n  /** Pixels per module when width is not supplied. */\n  scale?: number;\n  /** Dark and light colors as hexadecimal RGBA strings. */\n  color?: {\n    dark?: string;\n    light?: string;\n  };\n}\n\nexport const UPI_PAYMENT_SCHEME = \"upi://pay\" as const;\n\nconst DEFAULT_QR_OPTIONS = {\n  errorCorrectionLevel: \"M\",\n  width: 512,\n  margin: 2,\n} as const;\n\nfunction requiredText(value: string, field: string): string {\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new TypeError(`${field} is required`);\n  }\n\n  return value.trim();\n}\n\nfunction optionalText(\n  value: string | undefined,\n  field: string,\n  maxLength?: number,\n): string | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new TypeError(`${field} must be a non-empty string when provided`);\n  }\n\n  const normalized = value.trim();\n  if (maxLength !== undefined && normalized.length > maxLength) {\n    throw new RangeError(`${field} must be at most ${maxLength} characters`);\n  }\n\n  return normalized;\n}\n\n/**\n * Normalize an INR amount without silently rounding it.\n *\n * Decimal strings are recommended so callers do not introduce floating-point\n * rounding before the value reaches this function.\n */\nexport function normalizeUpiAmount(value: string | number): string {\n  if (typeof value !== \"string\" && typeof value !== \"number\") {\n    throw new TypeError(\"amount must be a string or number\");\n  }\n\n  if (typeof value === \"number\" && !Number.isFinite(value)) {\n    throw new TypeError(\"amount must be finite\");\n  }\n\n  const candidate = String(value).trim();\n  const match = /^(0|[1-9]\\d*)(?:\\.(\\d{1,2}))?$/.exec(candidate);\n\n  if (!match) {\n    throw new TypeError(\n      \"amount must be a positive decimal with no more than two decimal places\",\n    );\n  }\n\n  const whole = match[1];\n  const fraction = (match[2] ?? \"\").padEnd(2, \"0\");\n\n  if (BigInt(whole) === 0n && fraction === \"00\") {\n    throw new RangeError(\"amount must be greater than zero\");\n  }\n\n  return `${whole}.${fraction}`;\n}\n\n/** Create the `upi://pay` URI that is encoded into the QR code. */\nexport function createUpiPaymentUri(options: UpiPaymentOptions): string {\n  if (options === null || typeof options !== \"object\") {\n    throw new TypeError(\"payment options are required\");\n  }\n\n  const payeeVpa = requiredText(options.payeeVpa, \"payeeVpa\");\n  if (!/^[^\\s@]+@[^\\s@]+$/.test(payeeVpa)) {\n    throw new TypeError(\"payeeVpa must be a valid UPI virtual payment address\");\n  }\n\n  const fields: Array<[string, string | undefined]> = [\n    [\"pa\", payeeVpa],\n    [\"pn\", requiredText(options.payeeName, \"payeeName\")],\n    [\"am\", normalizeUpiAmount(options.amount)],\n    [\"cu\", \"INR\"],\n    [\"tr\", optionalText(options.transactionRef, \"transactionRef\", 35)],\n    [\"tn\", optionalText(options.transactionNote, \"transactionNote\")],\n    [\"mc\", optionalText(options.merchantCode, \"merchantCode\")],\n  ];\n\n  const query = fields\n    .filter((field): field is [string, string] => field[1] !== undefined)\n    .map(\n      ([key, value]) =>\n        `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,\n    )\n    .join(\"&\");\n\n  return `${UPI_PAYMENT_SCHEME}?${query}`;\n}\n\n/** Generate a PNG QR code as a data URL. Works in Node.js and browser bundlers. */\nexport function generateUpiQrDataUrl(\n  payment: UpiPaymentOptions,\n  qrOptions: UpiQrOptions = {},\n): Promise<string> {\n  const options: QRCodeToDataURLOptions = {\n    ...DEFAULT_QR_OPTIONS,\n    ...qrOptions,\n    type: \"image/png\",\n  };\n\n  return QRCode.toDataURL(createUpiPaymentUri(payment), options);\n}\n\n/** Generate a QR code as an SVG string. */\nexport function generateUpiQrSvg(\n  payment: UpiPaymentOptions,\n  qrOptions: UpiQrOptions = {},\n): Promise<string> {\n  const options: QRCodeToStringOptions = {\n    ...DEFAULT_QR_OPTIONS,\n    ...qrOptions,\n    type: \"svg\",\n  };\n\n  return QRCode.toString(createUpiPaymentUri(payment), options);\n}\n"],"mappings":"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","names":["QRCode"]}

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+import { QRCodeErrorCorrectionLevel } from 'qrcode';
+
+/** Details encoded in a UPI payment QR code. */
+interface UpiPaymentOptions {
+    /** Payee virtual payment address, for example `merchant@bank`. */
+    payeeVpa: string;
+    /** Name displayed by the payer's UPI app. */
+    payeeName: string;
+    /** Positive INR amount with no more than two decimal places. Prefer a string. */
+    amount: string | number;
+    /** Merchant transaction reference. Dynamic merchant QRs should include this. */
+    transactionRef?: string;
+    /** Note displayed with the payment. */
+    transactionNote?: string;
+    /** Merchant category code, when supplied by the acquiring bank or PSP. */
+    merchantCode?: string;
+}
+/** Rendering controls shared by the PNG data URL and SVG generators. */
+interface UpiQrOptions {
+    /** Error-correction level. Defaults to `M`. */
+    errorCorrectionLevel?: QRCodeErrorCorrectionLevel;
+    /** Width in pixels. Defaults to 512. */
+    width?: number;
+    /** Quiet-zone width in QR modules. Defaults to 2. */
+    margin?: number;
+    /** Pixels per module when width is not supplied. */
+    scale?: number;
+    /** Dark and light colors as hexadecimal RGBA strings. */
+    color?: {
+        dark?: string;
+        light?: string;
+    };
+}
+declare const UPI_PAYMENT_SCHEME: "upi://pay";
+/**
+ * Normalize an INR amount without silently rounding it.
+ *
+ * Decimal strings are recommended so callers do not introduce floating-point
+ * rounding before the value reaches this function.
+ */
+declare function normalizeUpiAmount(value: string | number): string;
+/** Create the `upi://pay` URI that is encoded into the QR code. */
+declare function createUpiPaymentUri(options: UpiPaymentOptions): string;
+/** Generate a PNG QR code as a data URL. Works in Node.js and browser bundlers. */
+declare function generateUpiQrDataUrl(payment: UpiPaymentOptions, qrOptions?: UpiQrOptions): Promise<string>;
+/** Generate a QR code as an SVG string. */
+declare function generateUpiQrSvg(payment: UpiPaymentOptions, qrOptions?: UpiQrOptions): Promise<string>;
+
+export { UPI_PAYMENT_SCHEME, type UpiPaymentOptions, type UpiQrOptions, createUpiPaymentUri, generateUpiQrDataUrl, generateUpiQrSvg, normalizeUpiAmount };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { QRCodeErrorCorrectionLevel } from 'qrcode';
+
+/** Details encoded in a UPI payment QR code. */
+interface UpiPaymentOptions {
+    /** Payee virtual payment address, for example `merchant@bank`. */
+    payeeVpa: string;
+    /** Name displayed by the payer's UPI app. */
+    payeeName: string;
+    /** Positive INR amount with no more than two decimal places. Prefer a string. */
+    amount: string | number;
+    /** Merchant transaction reference. Dynamic merchant QRs should include this. */
+    transactionRef?: string;
+    /** Note displayed with the payment. */
+    transactionNote?: string;
+    /** Merchant category code, when supplied by the acquiring bank or PSP. */
+    merchantCode?: string;
+}
+/** Rendering controls shared by the PNG data URL and SVG generators. */
+interface UpiQrOptions {
+    /** Error-correction level. Defaults to `M`. */
+    errorCorrectionLevel?: QRCodeErrorCorrectionLevel;
+    /** Width in pixels. Defaults to 512. */
+    width?: number;
+    /** Quiet-zone width in QR modules. Defaults to 2. */
+    margin?: number;
+    /** Pixels per module when width is not supplied. */
+    scale?: number;
+    /** Dark and light colors as hexadecimal RGBA strings. */
+    color?: {
+        dark?: string;
+        light?: string;
+    };
+}
+declare const UPI_PAYMENT_SCHEME: "upi://pay";
+/**
+ * Normalize an INR amount without silently rounding it.
+ *
+ * Decimal strings are recommended so callers do not introduce floating-point
+ * rounding before the value reaches this function.
+ */
+declare function normalizeUpiAmount(value: string | number): string;
+/** Create the `upi://pay` URI that is encoded into the QR code. */
+declare function createUpiPaymentUri(options: UpiPaymentOptions): string;
+/** Generate a PNG QR code as a data URL. Works in Node.js and browser bundlers. */
+declare function generateUpiQrDataUrl(payment: UpiPaymentOptions, qrOptions?: UpiQrOptions): Promise<string>;
+/** Generate a QR code as an SVG string. */
+declare function generateUpiQrSvg(payment: UpiPaymentOptions, qrOptions?: UpiQrOptions): Promise<string>;
+
+export { UPI_PAYMENT_SCHEME, type UpiPaymentOptions, type UpiQrOptions, createUpiPaymentUri, generateUpiQrDataUrl, generateUpiQrSvg, normalizeUpiAmount };

package/dist/index.js

@@ -0,0 +1,94 @@
+// src/index.ts
+import QRCode from "qrcode";
+var UPI_PAYMENT_SCHEME = "upi://pay";
+var DEFAULT_QR_OPTIONS = {
+  errorCorrectionLevel: "M",
+  width: 512,
+  margin: 2
+};
+function requiredText(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} is required`);
+  }
+  return value.trim();
+}
+function optionalText(value, field, maxLength) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeError(`${field} must be a non-empty string when provided`);
+  }
+  const normalized = value.trim();
+  if (maxLength !== void 0 && normalized.length > maxLength) {
+    throw new RangeError(`${field} must be at most ${maxLength} characters`);
+  }
+  return normalized;
+}
+function normalizeUpiAmount(value) {
+  if (typeof value !== "string" && typeof value !== "number") {
+    throw new TypeError("amount must be a string or number");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError("amount must be finite");
+  }
+  const candidate = String(value).trim();
+  const match = /^(0|[1-9]\d*)(?:\.(\d{1,2}))?$/.exec(candidate);
+  if (!match) {
+    throw new TypeError(
+      "amount must be a positive decimal with no more than two decimal places"
+    );
+  }
+  const whole = match[1];
+  const fraction = (match[2] ?? "").padEnd(2, "0");
+  if (BigInt(whole) === 0n && fraction === "00") {
+    throw new RangeError("amount must be greater than zero");
+  }
+  return `${whole}.${fraction}`;
+}
+function createUpiPaymentUri(options) {
+  if (options === null || typeof options !== "object") {
+    throw new TypeError("payment options are required");
+  }
+  const payeeVpa = requiredText(options.payeeVpa, "payeeVpa");
+  if (!/^[^\s@]+@[^\s@]+$/.test(payeeVpa)) {
+    throw new TypeError("payeeVpa must be a valid UPI virtual payment address");
+  }
+  const fields = [
+    ["pa", payeeVpa],
+    ["pn", requiredText(options.payeeName, "payeeName")],
+    ["am", normalizeUpiAmount(options.amount)],
+    ["cu", "INR"],
+    ["tr", optionalText(options.transactionRef, "transactionRef", 35)],
+    ["tn", optionalText(options.transactionNote, "transactionNote")],
+    ["mc", optionalText(options.merchantCode, "merchantCode")]
+  ];
+  const query = fields.filter((field) => field[1] !== void 0).map(
+    ([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`
+  ).join("&");
+  return `${UPI_PAYMENT_SCHEME}?${query}`;
+}
+function generateUpiQrDataUrl(payment, qrOptions = {}) {
+  const options = {
+    ...DEFAULT_QR_OPTIONS,
+    ...qrOptions,
+    type: "image/png"
+  };
+  return QRCode.toDataURL(createUpiPaymentUri(payment), options);
+}
+function generateUpiQrSvg(payment, qrOptions = {}) {
+  const options = {
+    ...DEFAULT_QR_OPTIONS,
+    ...qrOptions,
+    type: "svg"
+  };
+  return QRCode.toString(createUpiPaymentUri(payment), options);
+}
+export {
+  UPI_PAYMENT_SCHEME,
+  createUpiPaymentUri,
+  generateUpiQrDataUrl,
+  generateUpiQrSvg,
+  normalizeUpiAmount
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import QRCode from \"qrcode\";\nimport type {\n  QRCodeErrorCorrectionLevel,\n  QRCodeToDataURLOptions,\n  QRCodeToStringOptions,\n} from \"qrcode\";\n\n/** Details encoded in a UPI payment QR code. */\nexport interface UpiPaymentOptions {\n  /** Payee virtual payment address, for example `merchant@bank`. */\n  payeeVpa: string;\n  /** Name displayed by the payer's UPI app. */\n  payeeName: string;\n  /** Positive INR amount with no more than two decimal places. Prefer a string. */\n  amount: string | number;\n  /** Merchant transaction reference. Dynamic merchant QRs should include this. */\n  transactionRef?: string;\n  /** Note displayed with the payment. */\n  transactionNote?: string;\n  /** Merchant category code, when supplied by the acquiring bank or PSP. */\n  merchantCode?: string;\n}\n\n/** Rendering controls shared by the PNG data URL and SVG generators. */\nexport interface UpiQrOptions {\n  /** Error-correction level. Defaults to `M`. */\n  errorCorrectionLevel?: QRCodeErrorCorrectionLevel;\n  /** Width in pixels. Defaults to 512. */\n  width?: number;\n  /** Quiet-zone width in QR modules. Defaults to 2. */\n  margin?: number;\n  /** Pixels per module when width is not supplied. */\n  scale?: number;\n  /** Dark and light colors as hexadecimal RGBA strings. */\n  color?: {\n    dark?: string;\n    light?: string;\n  };\n}\n\nexport const UPI_PAYMENT_SCHEME = \"upi://pay\" as const;\n\nconst DEFAULT_QR_OPTIONS = {\n  errorCorrectionLevel: \"M\",\n  width: 512,\n  margin: 2,\n} as const;\n\nfunction requiredText(value: string, field: string): string {\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new TypeError(`${field} is required`);\n  }\n\n  return value.trim();\n}\n\nfunction optionalText(\n  value: string | undefined,\n  field: string,\n  maxLength?: number,\n): string | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new TypeError(`${field} must be a non-empty string when provided`);\n  }\n\n  const normalized = value.trim();\n  if (maxLength !== undefined && normalized.length > maxLength) {\n    throw new RangeError(`${field} must be at most ${maxLength} characters`);\n  }\n\n  return normalized;\n}\n\n/**\n * Normalize an INR amount without silently rounding it.\n *\n * Decimal strings are recommended so callers do not introduce floating-point\n * rounding before the value reaches this function.\n */\nexport function normalizeUpiAmount(value: string | number): string {\n  if (typeof value !== \"string\" && typeof value !== \"number\") {\n    throw new TypeError(\"amount must be a string or number\");\n  }\n\n  if (typeof value === \"number\" && !Number.isFinite(value)) {\n    throw new TypeError(\"amount must be finite\");\n  }\n\n  const candidate = String(value).trim();\n  const match = /^(0|[1-9]\\d*)(?:\\.(\\d{1,2}))?$/.exec(candidate);\n\n  if (!match) {\n    throw new TypeError(\n      \"amount must be a positive decimal with no more than two decimal places\",\n    );\n  }\n\n  const whole = match[1];\n  const fraction = (match[2] ?? \"\").padEnd(2, \"0\");\n\n  if (BigInt(whole) === 0n && fraction === \"00\") {\n    throw new RangeError(\"amount must be greater than zero\");\n  }\n\n  return `${whole}.${fraction}`;\n}\n\n/** Create the `upi://pay` URI that is encoded into the QR code. */\nexport function createUpiPaymentUri(options: UpiPaymentOptions): string {\n  if (options === null || typeof options !== \"object\") {\n    throw new TypeError(\"payment options are required\");\n  }\n\n  const payeeVpa = requiredText(options.payeeVpa, \"payeeVpa\");\n  if (!/^[^\\s@]+@[^\\s@]+$/.test(payeeVpa)) {\n    throw new TypeError(\"payeeVpa must be a valid UPI virtual payment address\");\n  }\n\n  const fields: Array<[string, string | undefined]> = [\n    [\"pa\", payeeVpa],\n    [\"pn\", requiredText(options.payeeName, \"payeeName\")],\n    [\"am\", normalizeUpiAmount(options.amount)],\n    [\"cu\", \"INR\"],\n    [\"tr\", optionalText(options.transactionRef, \"transactionRef\", 35)],\n    [\"tn\", optionalText(options.transactionNote, \"transactionNote\")],\n    [\"mc\", optionalText(options.merchantCode, \"merchantCode\")],\n  ];\n\n  const query = fields\n    .filter((field): field is [string, string] => field[1] !== undefined)\n    .map(\n      ([key, value]) =>\n        `${encodeURIComponent(key)}=${encodeURIComponent(value)}`,\n    )\n    .join(\"&\");\n\n  return `${UPI_PAYMENT_SCHEME}?${query}`;\n}\n\n/** Generate a PNG QR code as a data URL. Works in Node.js and browser bundlers. */\nexport function generateUpiQrDataUrl(\n  payment: UpiPaymentOptions,\n  qrOptions: UpiQrOptions = {},\n): Promise<string> {\n  const options: QRCodeToDataURLOptions = {\n    ...DEFAULT_QR_OPTIONS,\n    ...qrOptions,\n    type: \"image/png\",\n  };\n\n  return QRCode.toDataURL(createUpiPaymentUri(payment), options);\n}\n\n/** Generate a QR code as an SVG string. */\nexport function generateUpiQrSvg(\n  payment: UpiPaymentOptions,\n  qrOptions: UpiQrOptions = {},\n): Promise<string> {\n  const options: QRCodeToStringOptions = {\n    ...DEFAULT_QR_OPTIONS,\n    ...qrOptions,\n    type: \"svg\",\n  };\n\n  return QRCode.toString(createUpiPaymentUri(payment), options);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "upi-qr-code-generator",
+  "version": "1.0.0",
+  "description": "Generate UPI payment URIs and QR codes with a pre-filled amount in Node.js and browsers.",
+  "keywords": [
+    "upi",
+    "qr-code",
+    "payments",
+    "india",
+    "javascript",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "techpool",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/techpool/upi-qr-code-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/techpool/upi-qr-code-generator/issues"
+  },
+  "homepage": "https://github.com/techpool/upi-qr-code-generator#readme",
+  "scripts": {
+    "build": "tsup",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/qrcode": "^1.5.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.0"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  }
+}