Major Upgrade100% Backward Compatible

Migrating to Version 3.0.0

Version 3.0.0 introduces automated transaction splitting under NPCI guidelines, Zod 4 runtime schema validation, transaction metadata, and paise-level precision integer math.

Upgrading the Package

Install the latest release using your package manager:

bash

npm install @omkarbhosale/upiqr@latest

Key Changes & New Features

1Automated Transaction Splitting (splitTransactionQR)

Payments exceeding ₹2,000 can now be automatically chunked into ₹1,999 intervals. This helps merchants avoid PPI wallet interchange fees while maintaining high payment success rates.

2Zod 4 Schema Validation

All inputs are strictly validated at runtime. Invalid UPI IDs, non-positive amounts, or numbers exceeding bounds throw structured validation errors before QR generation begins.

3Transaction Metadata Fields

You can now pass optional metadata parameters: name (Payee Name), note (Transaction Note / Memo), and currency (defaults to INR).

4Paise-Level Precision Integer Math

All amount calculations operate on integer paise (Math.round(AMOUNT * 100)). This eliminates standard IEEE-754 floating point rounding drift (e.g. 1999.0000000002).

Before & After Comparison

See how your integration code evolves from v2 to v3:

Legacy (v1.x / v2.x)

v2-implementation.js
// v1.x / v2.x - Default import only, basic parameters
import generateQR from "@omkarbhosale/upiqr";

try {
  const qr = await generateQR({
    UPI_ID: "store@upi",
    AMOUNT: 5000 // In v2, large amounts generated a single QR with no splitting
  });
} catch (e) {
  // Generic error string
}

Modern (v3.0.0)

v3-implementation.ts
// v3.0.0 - Named imports, metadata, and automatic splitting
import { generateQR, splitTransactionQR } from "@omkarbhosale/upiqr";

try {
  // Option A: For amounts <= ₹2,000 with metadata
  const single = await generateQR({
    UPI_ID: "store@upi",
    AMOUNT: 1500,
    name: "Omkar Store",
    note: "Invoice #1092"
  });

  // Option B: For amounts > ₹2,000, automatically chunk into ₹1,999 parts
  const splits = await splitTransactionQR({
    UPI_ID: "store@upi",
    AMOUNT: 5000,
    name: "Omkar Store",
    note: "Invoice #1092"
  });
  // Splits into: ₹1,999 + ₹1,999 + ₹1,002
} catch (error) {
  // Detailed Zod 4 error format:
  // "Validation error: UPI_ID: Invalid UPI ID format..."
  console.error(error.message);
}

Updated Error Handling Format

In v3.0.0, if validation fails, the thrown error follows a standardized format:

Validation error: <field>: <message>

For example:

Validation error: UPI_ID: Invalid UPI ID format. Expected format: username@bank
Validation error: AMOUNT: Amount must be greater than 0
Validation error: AMOUNT: Single QR amount cannot exceed ₹1,00,000

Migration Checklist

Update package dependency to @omkarbhosale/upiqr@^3.0.0

Switch to named imports: import { generateQR, splitTransactionQR } from "@omkarbhosale/upiqr"

Use splitTransactionQR in checkout flows where orders exceed ₹2,000

Add payee name and transaction note for clearer customer bank statements

Previous PageInstallation & Setup Next Page generateQR()