upi 2.0.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69ebd28c841dea94af52286485d067afc224f52523684d5bb3cbcacb9c79322a
-  data.tar.gz: 4dad7fcf78afab8b327b01ee8310e2522181f76f4b8c0e3acb09b6d8f1c5ab4c
+  metadata.gz: 0c35150decd0ea8da417f11c7d5513cdf82a3609a61b071d9e41d6977ec0b802
+  data.tar.gz: d24b6754719ce81625612e38827d8a453df4d9a09b1a7d6966ff71c6972f0289
 SHA512:
-  metadata.gz: 2e5e58ab3704147e279eda86fa89f2bcf40a5dafc0f5849a0ba91223265be59ec94e215f5dc104c8a5eca807f28f053c27a94b3dcd4a7fa4b67c7fb34c195d97
-  data.tar.gz: 68e63cd763bba3a9db65ef0137466fe58462203befb6feaae7a983fc29863f425c8415953580108f045584ece2551b612050b8cb7ff253ba9559ff821d3b1d9e
+  metadata.gz: 5eba315c7f151124b1087ceba8555358fa5b95e3f07bc208e314b7f82f7497ea9617a9cab45bc7599a29574ef739b8e38a9067a68c3f10b9cf5aab100d9271f3
+  data.tar.gz: 7fe580edf651ff6eb855c66996fb7013121800a96ef5d8c8f6dc2a3690c9a14847d7cdf403ed3b78b6b59f59a005076de5b2e4b0d52c445486754e2db083f3c6

data/.rubocop.yml

@@ -15,11 +15,16 @@ Layout/LineLength:
 Metrics/MethodLength:
   Max: 60
 
-Metrics/BlockLength:
-  Max: 150
-
 Metrics/ParameterLists:
   Max: 15
 
 Metrics/AbcSize:
   Max: 20
+
+Metrics/ClassLength:
+  Max: 250
+
+Metrics/BlockLength:
+  Max: 150
+  Exclude:
+    - 'spec/**/*_spec.rb'

data/CHANGELOG.md

@@ -1,6 +1,54 @@
 ## [Unreleased]
 - In the making
 
+## [3.0.0] - 2026-09-17
+
+Correctness release. Earlier versions could emit a UPI URI that violated the NPCI
+UPI Linking Specification. The QR code still scanned, so the only symptom was a
+payment that failed in the payer's app, seemingly at random, depending on the
+amount and note involved.
+
+### Fixed
+- Spaces are now percent-encoded as `%20` instead of `+`. The specification's own
+  example URIs use `%20`; `+` is only correct for HTML form bodies, and PSP apps
+  that decode strictly showed names like `Test+User`.
+- Amounts are normalised to exactly two decimal places. `1499.5` now emits
+  `am=1499.50`, and float representation noise (`0.1 + 0.2`) no longer emits
+  `am=0.30000000000000004`, which PSP apps reject.
+- An amount with more than two decimal places, a zero amount, or a negative amount
+  now raises `Upi::ValidationError` instead of producing an unpayable QR code.
+- `am` and `tn` are omitted entirely when not supplied. Previously every call
+  without an amount emitted `am=0&tn=`, which Google Pay and PhonePe reject.
+- Values can no longer break out of the query string. A note containing `&` or `#`
+  used to truncate or forge parameters in `no_url_parse: false` mode.
+- PNG output is sized by module rather than pinned to a 300px canvas, so a longer
+  payload produces a larger image instead of modules too small to scan reliably.
+- `#upi_content` and `#generate_qr` no longer mutate the instance. `#params` is
+  frozen, calls no longer leak into one another, and instances can be shared.
+
+### Added
+- Validation of every field against the specification: payee address format,
+  four-digit ISO 18245 merchant code, `INR`-only currency, 50-character note
+  limit, 35-character alphanumeric references, and `http(s)`-only URLs.
+- `transaction_ref_id` is now required for merchant transactions carrying an
+  amount, as the specification mandates, and `Upi::Generator.generate_reference`
+  builds a unique one. A reused reference is rejected by PSPs as a duplicate,
+  which is why a QR with a hard-coded reference works once and then stops.
+- `min_amount:` for the `mam` tag, which lets the payer edit the amount down to a
+  floor.
+- `initiation_mode:` for the `mode` tag, with `MODE_QR` and friends. Opt-in.
+- `level:` and renderer options on `#generate_qr`.
+- `Upi::ValidationError`.
+
+### Changed
+- Parameters are emitted in the order used by the specification's examples:
+  `pa, pn, mc, tid, tr, tn, am, mam, cu, url, mode`.
+- `no_url_parse: false` now means "leave URL-safe punctuation readable" rather
+  than "do not escape anything"; separators are always escaped in both modes.
+- `#params` returns the frozen constructor parameters, not the last call's state.
+- QR error correction defaults to `:m` rather than rqrcode's `:h`, giving larger
+  modules at the same image size.
+
 ## [2.0.2] - 2024-09-08
 - For Individual Mode there need not be merchant code being sent. Removed default '0000'. Can be still added explicitly.
 - Changed the upi_content method to not parse the upi address and keep it as it is.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    upi (2.0.2)
+    upi (3.0.0)
       chunky_png
       rqrcode (= 2.2.0)
 

data/README.md

@@ -1,6 +1,8 @@
 # UPI
 
-The `upi` gem allows you to generate UPI QR codes for user-to-user payments. It supports both PNG and SVG formats for QR codes.
+The `upi` gem generates UPI payment URIs and QR codes, in PNG or SVG, that conform to the
+[NPCI UPI Linking Specification](https://www.npci.org.in/what-we-do/upi/product-overview)
+(common URL specification for deep linking and proximity integration).
 
 ## Installation
 
@@ -20,14 +22,12 @@ Or install it yourself as:
 
 ## Usage
 
-Generating a QR Code
-To generate a UPI QR code, you need to initialize the Upi::Generator class with the required parameters and call the generate_qr method.
+Initialize `Upi::Generator` with the payee details, then call `generate_qr` for a QR code or
+`upi_content` for the raw payment URI. Generator instances are immutable and safe to reuse
+and share across threads.
 
-### Example
+### Individual mode (P2P)
 
-## Individual Mode:
-
-### Create a new UPI QR code generator instance
 ```ruby
 require 'upi'
 
@@ -35,117 +35,207 @@ generator = Upi::Generator.new(
   upi_id: 'test@upi',
   name: 'Test Name'
 )
+```
 
-# NOTE: For Individual Mode the Merchant Code is always 0000 which the code handles by default
+Do not pass `merchant_code` for individual payments; it is omitted entirely.
 
-```
+#### QR code in SVG format
 
-### Generate QR code in SVG format
 ```ruby
 svg_content = generator.generate_qr(100, 'Personal Payment', mode: :svg)
 File.write('qr_code.svg', svg_content)
 ```
 
-### Generate QR code in PNG format
+#### QR code in PNG format
+
 ```ruby
 png_content = generator.generate_qr(100, 'Personal Payment', mode: :png)
 File.binwrite('qr_code.png', png_content)
 ```
 
-### Generating a Payment URL
-You can generate a UPI payment URL suitable for use in HTML links by using the generate_url method. This URL can be used as the href attribute in a "Pay Now" button or link.
+#### Payment URI
+
+`upi_content` returns a UPI URI you can use as the `href` of a "Pay Now" link:
 
 ```ruby
-# Generate UPI payment URL
 payment_url = generator.upi_content(100, 'Personal Payment')
-puts payment_url
-
-# The generate_url method returns a UPI URI string that can be used as a link in your HTML:
+# => "upi://pay?pa=test@upi&pn=Test%20Name&tn=Personal%20Payment&am=100.00&cu=INR"
 ```
 
 ```html
 <a href="<%= payment_url %>">Pay Now</a>
 ```
 
-## Merchant Mode:
+#### Letting the payer choose the amount
+
+Omit the amount and the `am` tag is left out, so the payer types their own. Never pass `0` for
+this — UPI apps reject `am=0`, and the gem raises rather than emit it.
 
-### Create a new UPI QR code generator instance
 ```ruby
-require 'upi'
+generator.upi_content
+# => "upi://pay?pa=test@upi&pn=Test%20Name&cu=INR"
+```
+
+### Merchant mode (P2M)
+
+Pass a four-digit [ISO 18245](https://en.wikipedia.org/wiki/Merchant_category_code) merchant
+category code:
 
+```ruby
 generator = Upi::Generator.new(
-  upi_id: 'test@upi',
+  upi_id: 'merchant@upi',
   name: 'Test Name',
-  merchant_code: '1234',
-  currency: 'INR'
+  merchant_code: '5411'
 )
+```
 
-# NOTE: For Merchant Mode the Merchant Code needs to be set explicitly
+A merchant payment that carries an amount **must** also carry a transaction reference (`tr`),
+and that reference **must be unique for every payment attempt**. PSPs reject a reference they
+have already seen as a duplicate, so a QR code with a hard-coded reference works once and then
+silently stops. `Upi::Generator.generate_reference` builds a suitable one:
 
+```ruby
+reference = Upi::Generator.generate_reference('ORD')  # => "ORD20260917131656E4BBC91A"
+
+svg_content = generator.generate_qr(
+  500, 'Payment for Goods',
+  transaction_ref_id: reference,
+  transaction_id: 'TXN456',
+  url: 'https://merchant.com/payment',
+  mode: :svg
+)
 ```
 
-### Generate QR code in SVG format
+In practice the reference is your own order or invoice number, which is what makes
+reconciliation work:
+
 ```ruby
-svg_content = generator.generate_qr(500, 'Payment for Goods', transaction_ref_id: 'REF123', transaction_id: 'TXN456', url: 'https://merchant.com/payment', mode: :svg)
-File.write('qr_code_merchant.svg', svg_content)
+generator.upi_content(500, 'Payment for Goods', transaction_ref_id: "ORD#{order.id}")
 ```
 
-### Generate QR code in PNG format
+Leaving the amount out produces a static "shop counter" QR, which needs no reference because
+the payer supplies a fresh one each time:
+
 ```ruby
-png_content = generator.generate_qr(500, 'Payment for Goods', transaction_ref_id: 'REF123', transaction_id: 'TXN456', url: 'https://merchant.com/payment', mode: :png)
-File.binwrite('qr_code_merchant.png', png_content)
+generator.upi_content
+# => "upi://pay?pa=merchant@upi&pn=Test%20Name&mc=5411&cu=INR"
 ```
 
-### Generating a Payment URL
-You can generate a UPI payment URL suitable for use in HTML links by using the generate_url method. This URL can be used as the href attribute in a "Pay Now" button or link.
+### Letting the payer pay at least a minimum
 
+`min_amount` maps to the `mam` tag: the amount becomes editable, down to that floor.
 
 ```ruby
-# Generate UPI payment URL
-payment_url = generator.upi_content(500, 'Payment for Goods', transaction_ref_id: 'REF123', transaction_id: 'TXN456', url: 'https://merchant.com/payment')
-puts payment_url
-
-# The generate_url method returns a UPI URI string that can be used as a link in your HTML:
+generator.upi_content(500, 'Donation', transaction_ref_id: 'ORD90211', min_amount: 100)
+# => "upi://pay?pa=merchant@upi&pn=Test%20Name&mc=5411&tr=ORD90211&tn=Donation&am=500.00&mam=100.00&cu=INR"
 ```
 
-```html
-<a href="<%= payment_url %>">Pay Now</a>
+## Parameters
+
+### `Upi::Generator.new`
+
+| Parameter | Required | Notes |
+| --- | --- | --- |
+| `upi_id:` | yes | Payee VPA, `name@psp`. Max 255 characters. |
+| `name:` | yes | Payee name shown on the payer's confirmation screen. Max 99 characters. |
+| `currency:` | no | Defaults to `'INR'`, the only value UPI supports. |
+| `merchant_code:` | no | Four-digit ISO 18245 category code. Its presence selects merchant mode. |
+| `no_url_parse:` | no | Encoding strictness, see [Encoding](#encoding). Defaults to `true`. |
+
+### `#upi_content` and `#generate_qr`
+
+Both take the same payment arguments; `generate_qr` adds the rendering ones.
+
+| Parameter | Notes |
+| --- | --- |
+| `amount` | First positional. Omit to let the payer choose. Max two decimal places. |
+| `note` | Second positional. Maps to `tn`. Max 50 characters. |
+| `transaction_ref_id:` | `tr`. Mandatory for merchant payments with an amount. Max 35 alphanumeric characters. |
+| `transaction_id:` | `tid`, PSP-generated when present. Max 35 alphanumeric characters. |
+| `url:` | `http(s)` URL with further transaction detail. |
+| `min_amount:` | `mam`. Makes the amount editable down to this floor. |
+| `initiation_mode:` | `mode`. Opt-in, see [Initiation mode](#initiation-mode). |
+| `mode:` | `generate_qr` only. `:svg` (default) or `:png`. |
+| `level:` | `generate_qr` only. QR error correction: `:l`, `:m` (default), `:q`, `:h`. |
+
+Any other keyword to `generate_qr` is passed through to the renderer, so
+`module_px_size:`, `border_modules:`, `color:` and the rest of the
+[rqrcode](https://github.com/whomwah/rqrcode) options still work:
+
+```ruby
+generator.generate_qr(100, 'Tea', mode: :png, module_px_size: 12, color: '333')
 ```
 
-#### In the example above:
+## Amounts
 
-* Replace `'test@upi'` with the UPI ID of the recipient.
-* Replace `'Test Name'` with the recipient's name.
-* The `amount` parameter specifies the payment amount.
-* `note` is an optional field to include additional information.
-Parameters
-* upi_id: The UPI ID of the recipient.
-* name: The name of the recipient.
-* amount: The amount for the payment (required for UPI transactions).
-* currency: Currency code (default is 'INR').
-* note: Additional note or description for the payment.
-* merchant_code: Optional merchant code.
-* transaction_ref_id: Optional transaction reference ID.
-* transaction_id: Optional transaction ID.
-* url: Optional URL for additional information or payment redirect.
+Amounts are normalised to the two-decimal format UPI requires, and anything that cannot be
+represented that way raises rather than producing an unpayable QR code.
 
-#### Handling PNG and SVG
-You can specify the format of the QR code by using the mode parameter:
+```ruby
+generator.upi_content(100)            # => "...&am=100.00&..."
+generator.upi_content(1499.5)         # => "...&am=1499.50&..."
+generator.upi_content(0.1 + 0.2)      # => "...&am=0.30&..."     float noise is discarded
+generator.upi_content(BigDecimal('99.9'))
 
-* mode: :svg generates an SVG format QR code.
-* mode: :png generates a PNG format QR code.
+generator.upi_content(100.456)        # raises Upi::ValidationError, more than two decimals
+generator.upi_content(0)              # raises Upi::ValidationError, UPI apps reject am=0
+```
 
-## No URI parse mode
+Pass a `String` or `BigDecimal` when the amount comes from a currency column, so no float ever
+touches it.
 
-If you want to generate a QR code without parsing the UPI address, you can use the no_uri_parse option:
+## Validation
+
+Every field is checked against the specification before a URI is built, and a failure raises
+`Upi::ValidationError` (a subclass of `Upi::Error`). This is deliberate: an invalid UPI URI
+still produces a perfectly scannable QR code, so without validation the only symptom is a
+payment that fails later, in the payer's app.
 
 ```ruby
-svg_content = generator.generate_qr(100, 'Personal Payment', no_uri_parse: true, mode: :svg)
-uri_content = generator.upi_content(100, 'Personal Payment', no_uri_parse: true)
+Upi::Generator.new(upi_id: 'not-a-vpa', name: 'X')
+# Upi::ValidationError: upi_id "not-a-vpa" is not a valid UPI address (expected 'name@psp')
+```
 
-# The no_uri_parse option will generate the QR code without URI parsing the UPI address.
+## Encoding
+
+Values are percent-encoded per RFC 3986, with spaces as `%20`, matching the example URIs in
+the specification. `no_url_parse` selects how aggressive that is:
+
+* `true` (default) encodes down to the unreserved set.
+* `false` leaves URL-safe punctuation such as `:` and `/` readable.
+
+Either way the characters that would corrupt the query string — `&`, `#`, `%`, `+` and space —
+are always escaped, so a note like `Tea & Coffee #12` can never truncate the URI or forge
+another parameter. Redirect URLs keep their `://` readable in both modes.
+
+## Initiation mode
+
+The specification lists a `mode` tag (`01` for QR, `04` for intent). It is left out by default,
+since most PSP apps accept a URI without it and existing integrations rely on that. Opt in when
+you want it:
+
+```ruby
+generator.upi_content(500, 'Goods', transaction_ref_id: 'ORD1',
+                      initiation_mode: Upi::Generator::MODE_QR)
+# => "...&cu=INR&mode=01"
 ```
 
+Signed QR codes (`mode=02`, requiring the `sign` and `orgid` tags) are not supported.
+
+## Upgrading from 2.x
+
+3.0 changes the generated URI so that it complies with the specification. See the
+[CHANGELOG](CHANGELOG.md) for the full list. The changes most likely to affect you:
+
+* Spaces encode as `%20`, not `+`, and parameters are emitted in the specification's order, so
+  any test asserting an exact URI string needs updating.
+* Amounts always carry two decimals: `am=100` is now `am=100.00`.
+* Calling without an amount no longer emits `am=0&tn=`; both tags are omitted.
+* Invalid input now raises `Upi::ValidationError` instead of silently producing a broken QR
+  code. Merchant payments with an amount now require `transaction_ref_id`.
+* `#params` returns the frozen constructor parameters rather than the last call's state.
+* PNG output is sized by module rather than pinned to 300px, so images vary in size with the
+  payload. Pass `size:` or `module_px_size:` to control it.
 
 ## Development
 
@@ -155,7 +245,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/stingrayzboy/upi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/upi/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/stingrayzboy/upi. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/stingrayzboy/upi/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 

data/lib/upi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Upi
-  VERSION = '2.0.2'
+  VERSION = '3.0.0'
 end

data/lib/upi.rb

@@ -2,118 +2,366 @@
 
 require 'rqrcode'
 require 'chunky_png'
-require 'uri'
+require 'bigdecimal'
+require 'securerandom'
 require_relative 'upi/version'
 
 module Upi
-  # The Generator class is responsible for creating UPI QR codes and payment URLs.
+  # Base error class for the gem.
+  class Error < StandardError; end
+
+  # Raised when the supplied payment details cannot produce a spec-compliant UPI URI.
   #
-  # You can generate a QR code for a UPI payment in either SVG or PNG format,
-  # and also create a UPI payment URL for use in HTML links.
+  # Failing loudly at generation time is deliberate: an invalid UPI URI still
+  # produces a perfectly scannable QR code, so the only symptom is a payment
+  # that fails in the payer's app, long after the QR was handed out.
+  class ValidationError < Error; end
+
+  # Builds UPI payment URIs and QR codes that conform to the NPCI "UPI Linking
+  # Specifications" (common URL specification for deep linking and proximity
+  # integration, v1.6).
   #
-  # Example usage:
+  # The canonical example from that document is the shape this class targets:
   #
-  #   generator = Upi::Generator.new(
-  #     upi_id: 'test@upi',
-  #     name: 'Test Name'
-  #   )
+  #   upi://pay?pa=nadeem@npci&pn=nadeem%20chinna&mc=0000&tid=...&tr=...
+  #            &tn=Pay%20to%20mystar%20store&am=10&mam=null&cu=INR&url=https://...
   #
-  #   svg_content = generator.generate_qr(100, 'Personal Payment', mode: :svg)
-  #   png_content = generator.generate_qr(100, 'Personal Payment', mode: :png)
-  #   payment_url = generator.upi_content(100, 'Personal Payment')
+  # Example usage:
   #
-  # Parameters:
-  # - `upi_id`: The UPI ID of the recipient.
-  # - `name`: The name of the recipient.
-  # - `amount`: The payment amount (required for UPI transactions).
-  # - `currency`: The currency code (default is 'INR').
-  # - `note`: An optional note or description for the payment.
-  # - `merchant_code`: An optional merchant code.
-  # - `transaction_ref_id`: An optional transaction reference ID.
-  # - `transaction_id`: An optional transaction ID.
-  # - `url`: An optional URL for additional information or payment redirect.
+  #   generator = Upi::Generator.new(upi_id: 'test@upi', name: 'Test Name')
+  #   svg = generator.generate_qr(100, 'Personal Payment', mode: :svg)
+  #   png = generator.generate_qr(100, 'Personal Payment', mode: :png)
+  #   uri = generator.upi_content(100, 'Personal Payment')
   #
-  # @example
-  #   generator = Upi::Generator.new(
-  #     upi_id: 'test@upi',
-  #     name: 'Test Name'
-  #   )
-  #   svg_content = generator.generate_qr(100, 'Personal Payment', mode: :svg)
-  #   File.write('qr_code.svg', svg_content)
+  # Instances are immutable and safe to share between threads.
   #
-  # @see https://www.npci.org.in/what-we-do/upi/product-overview for more details on UPI protocol
+  # @see https://www.npci.org.in/what-we-do/upi/product-overview
   class Generator
+    # Currently the only currency UPI supports.
+    CURRENCY = 'INR'
+
+    # Transaction initiation modes from the specification's `mode` tag.
+    MODE_DEFAULT = '00'
+    MODE_QR = '01'
+    MODE_SECURE_QR = '02'
+    MODE_INTENT = '04'
+
+    # Field limits. `pa`/`pn` follow the NPCI field sizes; `tn` is the widely
+    # enforced 50-character transaction note limit; `tr`/`tid` are kept inside
+    # the shortest limit PSPs are known to apply.
+    MAX_LENGTHS = { pa: 255, pn: 99, tn: 50, tr: 35, tid: 35 }.freeze
+
+    # A virtual payment address: `local@psp`.
+    VPA_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9._-]{0,}@[A-Za-z][A-Za-z0-9.-]{0,}\z/.freeze
+
+    # Merchant category code, ISO 18245: exactly four digits.
+    MERCHANT_CODE_PATTERN = /\A\d{4}\z/.freeze
+
+    # Reference and transaction ids must be alphanumeric with no spaces.
+    REFERENCE_PATTERN = /\A[A-Za-z0-9._-]+\z/.freeze
+
+    NUMERIC_PATTERN = /\A\d+(\.\d+)?\z/.freeze
+
+    # Largest amount we will emit. Per-transaction ceilings are set by the bank
+    # and the merchant category, so this only catches obviously bad input.
+    MAX_AMOUNT = BigDecimal('10000000000')
+
+    # RFC 3986 unreserved set. Everything else is percent-encoded, which is what
+    # makes a space `%20` rather than `+`.
+    STRICT_UNSAFE = /[^A-Za-z0-9\-._~]/.freeze
+
+    # Leaves characters that are legal inside a query value untouched, so a
+    # redirect URL stays readable as `https://host/path` the way the NPCI
+    # examples show it. `&`, `#`, `%`, `+` and space are still escaped, so a
+    # value can never break out and forge another parameter.
+    LENIENT_UNSAFE = %r{[^A-Za-z0-9\-._~:/?=@!$'()*,;]}.freeze
+
+    # Emission order follows the example URIs in the specification.
+    PARAM_ORDER = %i[pa pn mc tid tr tn am mam cu url mode].freeze
+
+    # Renderer options accepted by rqrcode, used to reject a mistyped payment
+    # keyword rather than let it fall through to the renderer and quietly drop a
+    # field from the QR code.
+    SVG_OPTIONS = %i[fill use_path offset color shape_rendering module_size standalone
+                     viewbox svg_attributes].freeze
+    PNG_OPTIONS = %i[bit_depth border_modules color_mode color file fill module_px_size
+                     resize_exactly_to resize_gte_to size].freeze
+
     attr_reader :params, :no_url_parse
 
-    def initialize(upi_id:, name:, currency: 'INR', merchant_code: nil, no_url_parse: true)
-      @params = {
-        pa: upi_id,
-        pn: name,
-        am: '',
-        cu: currency,
-        tn: '',
-        mc: merchant_code,
-        tr: nil,
-        tid: nil,
-        url: nil
-      }.compact
+    # @param upi_id [String] payee VPA, e.g. `'merchant@upi'`
+    # @param name [String] payee name shown on the payer's confirmation screen
+    # @param currency [String] ISO 4217 code; UPI only supports `'INR'`
+    # @param merchant_code [String, nil] four-digit ISO 18245 merchant category
+    #   code. Supplying it puts the generator in merchant (P2M) mode.
+    # @param no_url_parse [Boolean] `true` (default) percent-encodes values down
+    #   to the RFC 3986 unreserved set; `false` leaves URL-safe punctuation
+    #   readable. Both modes always escape the characters that would otherwise
+    #   corrupt the query string.
+    def initialize(upi_id:, name:, currency: CURRENCY, merchant_code: nil, no_url_parse: true)
+      @upi_id = validate_vpa!(upi_id)
+      @name = validate_text!(name, :pn, 'name')
+      @currency = validate_currency!(currency)
+      @merchant_code = validate_merchant_code!(merchant_code)
       @no_url_parse = no_url_parse
+      @params = { pa: @upi_id, pn: @name, mc: @merchant_code, cu: @currency }.compact.freeze
     end
 
-    def generate_qr(amount = '0', note = '', transaction_ref_id: nil, transaction_id: nil, url: nil, mode: :svg)
-      content = upi_content(amount, note, transaction_ref_id: transaction_ref_id, transaction_id: transaction_id, url: url)
-      qrcode = RQRCode::QRCode.new(content)
-      generate_transaction(amount, note, transaction_id, transaction_ref_id, url)
-
-      case mode
-      when :svg
-        qrcode.as_svg(
-          color: '000',
-          shape_rendering: 'crispEdges',
-          module_size: 11
-        )
-      when :png
-        png = qrcode.as_png(
-          bit_depth: 1,
-          border_modules: 4,
-          color_mode: ChunkyPNG::COLOR_GRAYSCALE,
-          color: 'black',
-          file: nil,
-          fill: 'white',
-          module_px_size: 6, # Adjust size as needed
-          resize_exactly_to: false,
-          resize_gte_to: false,
-          size: 300 # Adjust size as needed
-        )
-        png.to_s
+    # Generates a unique transaction reference suitable for the `tr` field.
+    #
+    # A `tr` must be unique per payment attempt: PSPs reject a repeat of one
+    # they have already seen, which is why a QR carrying a hard-coded reference
+    # works once and then quietly stops.
+    #
+    # @param prefix [String] alphanumeric prefix to make references recognisable
+    # @return [String]
+    def self.generate_reference(prefix = 'UPI')
+      raise ValidationError, "reference prefix #{prefix.inspect} must be alphanumeric" unless prefix.to_s.match?(REFERENCE_PATTERN)
+
+      "#{prefix}#{Time.now.strftime("%Y%m%d%H%M%S")}#{SecureRandom.hex(4).upcase}"
+    end
+
+    # Builds the `upi://pay?...` URI.
+    #
+    # @param amount [Numeric, String, nil] payment amount. Omit it (or pass nil)
+    #   to let the payer type an amount; UPI apps reject `am=0`.
+    # @param note [String, nil] transaction note, max 50 characters
+    # @param transaction_ref_id [String, nil] `tr`. Mandatory for merchant
+    #   transactions carrying an amount, and must be unique per attempt.
+    # @param transaction_id [String, nil] `tid`, PSP-generated when present
+    # @param url [String, nil] `http`/`https` transaction detail URL
+    # @param min_amount [Numeric, String, nil] `mam`. When given, the payer can
+    #   edit the amount down to this floor.
+    # @param initiation_mode [String, nil] `mode` tag, e.g. {MODE_QR}
+    # @return [String]
+    def upi_content(amount = nil, note = nil, transaction_ref_id: nil, transaction_id: nil,
+                    url: nil, min_amount: nil, initiation_mode: nil)
+      fields = build_fields(amount, note, transaction_ref_id, transaction_id, url,
+                            min_amount, initiation_mode)
+      query = PARAM_ORDER.map do |key|
+        next if key == :pa
+
+        value = fields[key]
+        "#{key}=#{encode(value, lenient: key == :url)}" unless value.nil?
+      end.compact
+
+      "upi://pay?pa=#{fields[:pa]}&#{query.join("&")}"
+    end
+
+    # Renders the payment URI as a QR code.
+    #
+    # @param mode [Symbol] `:svg` (default) or `:png` output format
+    # @param level [Symbol] QR error correction level, `:l`, `:m`, `:q` or `:h`
+    # @param render_options [Hash] passed through to the rqrcode renderer,
+    #   overriding the defaults (e.g. `module_px_size:`, `module_size:`)
+    # @return [String] SVG markup, or raw PNG bytes
+    # @see #upi_content for the payment parameters
+    def generate_qr(amount = nil, note = nil, transaction_ref_id: nil, transaction_id: nil,
+                    url: nil, min_amount: nil, initiation_mode: nil,
+                    mode: :svg, level: :m, **render_options)
+      raise ArgumentError, "Unsupported mode: #{mode}. Use :svg or :png." unless %i[svg png].include?(mode)
+
+      validate_render_options!(render_options, mode)
+      content = upi_content(amount, note, transaction_ref_id: transaction_ref_id,
+                                          transaction_id: transaction_id, url: url,
+                                          min_amount: min_amount, initiation_mode: initiation_mode)
+      qrcode = RQRCode::QRCode.new(content, level: level)
+
+      mode == :svg ? render_svg(qrcode, render_options) : render_png(qrcode, render_options)
+    end
+
+    private
+
+    def build_fields(amount, note, transaction_ref_id, transaction_id, url, min_amount, initiation_mode)
+      normalized_amount = normalize_amount(amount, 'amount')
+      reference = validate_reference!(transaction_ref_id, :tr, 'transaction_ref_id')
+      require_reference!(reference, normalized_amount)
+
+      params.merge(
+        tid: validate_reference!(transaction_id, :tid, 'transaction_id'),
+        tr: reference,
+        tn: presence(validate_text!(note, :tn, 'note')),
+        am: normalized_amount,
+        mam: normalize_min_amount(min_amount, normalized_amount),
+        url: validate_url!(url),
+        mode: validate_initiation_mode!(initiation_mode)
+      )
+    end
+
+    # The specification marks `tr` mandatory for merchant transactions and for
+    # dynamic (amount-bearing) URLs. Without it a PSP's risk engine sees an
+    # amount-carrying merchant payload with nothing to reconcile against, and
+    # rejects it behind a generic error.
+    def require_reference!(reference, amount)
+      return if reference || @merchant_code.nil? || amount.nil?
+
+      raise ValidationError,
+            'transaction_ref_id is mandatory for merchant transactions with an amount, ' \
+            'and must be unique per payment attempt. ' \
+            'Use Upi::Generator.generate_reference to build one.'
+    end
+
+    def validate_vpa!(upi_id)
+      value = upi_id.to_s.strip
+      raise ValidationError, 'upi_id is required' if value.empty?
+
+      raise ValidationError, "upi_id must be at most #{MAX_LENGTHS[:pa]} characters" if value.length > MAX_LENGTHS[:pa]
+      raise ValidationError, "upi_id #{upi_id.inspect} is not a valid UPI address (expected 'name@psp')" unless value.match?(VPA_PATTERN)
+
+      value
+    end
+
+    def validate_text!(text, key, label)
+      return nil if text.nil?
+
+      value = text.to_s.tr("\r\n\t", ' ').strip
+      if value.length > MAX_LENGTHS[key]
+        raise ValidationError,
+              "#{label} must be at most #{MAX_LENGTHS[key]} characters, got #{value.length}"
+      end
+      raise ValidationError, "#{label} is required" if key == :pn && value.empty?
+
+      value
+    end
+
+    def validate_currency!(currency)
+      value = currency.to_s.strip.upcase
+      raise ValidationError, "currency #{currency.inspect} is not supported; UPI only supports 'INR'" unless value == CURRENCY
+
+      value
+    end
+
+    def validate_merchant_code!(merchant_code)
+      return nil if merchant_code.nil?
+
+      value = merchant_code.to_s.strip
+      unless value.match?(MERCHANT_CODE_PATTERN)
+        raise ValidationError,
+              "merchant_code #{merchant_code.inspect} must be a four-digit ISO 18245 category code"
+      end
+
+      value
+    end
+
+    def validate_reference!(reference, key, label)
+      return nil if reference.nil?
+
+      value = reference.to_s.strip
+      return nil if value.empty?
+
+      raise ValidationError, "#{label} must be at most #{MAX_LENGTHS[key]} characters, got #{value.length}" if value.length > MAX_LENGTHS[key]
+      raise ValidationError, "#{label} #{reference.inspect} must be alphanumeric with no spaces" unless value.match?(REFERENCE_PATTERN)
+
+      value
+    end
+
+    def validate_url!(url)
+      return nil if url.nil?
+
+      value = url.to_s.strip
+      return nil if value.empty?
+      raise ValidationError, "url #{url.inspect} must start with http:// or https://" unless value.start_with?('http://', 'https://')
+
+      value
+    end
+
+    def validate_initiation_mode!(initiation_mode)
+      return nil if initiation_mode.nil?
+
+      value = initiation_mode.to_s
+      raise ValidationError, "initiation_mode #{initiation_mode.inspect} must be two digits" unless value.match?(/\A\d{2}\z/)
+
+      value
+    end
+
+    def normalize_min_amount(min_amount, amount)
+      normalized = normalize_amount(min_amount, 'min_amount')
+      return nil if normalized.nil?
+
+      raise ValidationError, "min_amount #{normalized} cannot exceed amount #{amount}" if amount && BigDecimal(normalized) > BigDecimal(amount)
+
+      normalized
+    end
+
+    # UPI amounts are decimal with at most two places. Emitting anything else --
+    # `am=0`, `am=1499.5`, or the `0.30000000000000004` a float sum produces --
+    # is rejected by PSP apps, so normalize here and reject what cannot be
+    # represented rather than silently rounding someone's money.
+    def normalize_amount(amount, label)
+      return nil if amount.nil?
+      return nil if amount.is_a?(String) && amount.strip.empty?
+
+      decimal = to_decimal(amount, label)
+      raise ValidationError, "#{label} must be greater than zero, got #{amount.inspect}" unless decimal.positive?
+      raise ValidationError, "#{label} #{amount.inspect} is too large" if decimal > MAX_AMOUNT
+
+      if decimal != decimal.round(2)
+        raise ValidationError,
+              "#{label} #{amount.inspect} has more than two decimal places; " \
+              'UPI amounts allow at most two. Round it before passing it in.'
+      end
+
+      whole, fraction = decimal.to_s('F').split('.')
+      "#{whole}.#{fraction.to_s.ljust(2, "0")[0, 2]}"
+    end
+
+    def to_decimal(amount, label)
+      case amount
+      when BigDecimal then amount
+      when Integer then BigDecimal(amount)
+      # 15 significant digits discards IEEE representation noise (0.1 + 0.2)
+      # while preserving precision the caller actually meant.
+      when Float, Rational then BigDecimal(amount, 15)
+      when String
+        value = amount.strip
+        raise ValidationError, "#{label} #{amount.inspect} is not a valid number" unless value.match?(NUMERIC_PATTERN)
+
+        BigDecimal(value)
       else
-        raise ArgumentError, "Unsupported mode: #{mode}. Use :svg or :png."
+        raise ValidationError, "#{label} must be Numeric or String, got #{amount.class}"
       end
     end
 
-    def upi_content(amount = '0', note = '', transaction_ref_id: nil, transaction_id: nil, url: nil)
-      generate_transaction(amount, note, transaction_id, transaction_ref_id, url)
+    def presence(value)
+      value unless value.nil? || value.empty?
+    end
 
-      # Manually construct the UPI URI string without URI::UPI
-      query_string = if no_url_parse
-                       URI.encode_www_form(params.reject { |k, v| v.nil? || k == :pa })
-                     else
-                       params.reject { |k, v| v.nil? || k == :pa }.map { |k, v| "#{k}=#{v}" }.join('&')
-                     end
-      "upi://pay?pa=#{params[:pa]}&#{query_string}"
+    def encode(value, lenient: false)
+      pattern = lenient || !no_url_parse ? LENIENT_UNSAFE : STRICT_UNSAFE
+      value.to_s.gsub(pattern) { |char| char.bytes.map { |byte| format('%%%02X', byte) }.join }
     end
 
-    private
+    def validate_render_options!(options, mode)
+      allowed = mode == :svg ? SVG_OPTIONS : PNG_OPTIONS
+      unknown = options.keys - allowed
+      return if unknown.empty?
 
-    def generate_transaction(amount, note, transaction_id, transaction_ref_id, url)
-      @params[:am] = amount
-      @params[:tn] = note
-      @params[:tr] = transaction_ref_id
-      @params[:tid] = transaction_id
-      @params[:url] = url
-      @params
+      raise ArgumentError,
+            "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}. " \
+            "Payment details go to #upi_content's parameters; #{mode} renderer options are: " \
+            "#{allowed.join(", ")}."
     end
-  end
 
-  class Error < StandardError; end
+    def render_svg(qrcode, options)
+      qrcode.as_svg({ color: '000', shape_rendering: 'crispEdges', module_size: 11 }.merge(options))
+    end
+
+    # Sizing is driven by module size rather than a fixed canvas: a longer
+    # payload needs more modules, and pinning the canvas shrinks each module
+    # until scanners start to struggle.
+    def render_png(qrcode, options)
+      defaults = {
+        bit_depth: 1,
+        border_modules: 4,
+        color_mode: ChunkyPNG::COLOR_GRAYSCALE,
+        color: 'black',
+        file: nil,
+        fill: 'white',
+        module_px_size: 8,
+        resize_exactly_to: false,
+        resize_gte_to: false
+      }
+      qrcode.as_png(**defaults.merge(options)).to_s
+    end
+  end
 end

data/sig/upi/generator.rbs

@@ -1,16 +1,89 @@
 module Upi
+  class Error < StandardError
+  end
+
+  class ValidationError < Error
+  end
+
   class Generator
+    type amount = Numeric | String | nil
+    type fields = Hash[Symbol, String?]
+
+    CURRENCY: String
+    MODE_DEFAULT: String
+    MODE_QR: String
+    MODE_SECURE_QR: String
+    MODE_INTENT: String
+    MAX_LENGTHS: Hash[Symbol, Integer]
+    VPA_PATTERN: Regexp
+    MERCHANT_CODE_PATTERN: Regexp
+    REFERENCE_PATTERN: Regexp
+    NUMERIC_PATTERN: Regexp
+    MAX_AMOUNT: BigDecimal
+    STRICT_UNSAFE: Regexp
+    LENIENT_UNSAFE: Regexp
+    PARAM_ORDER: Array[Symbol]
+
+    @upi_id: String
+    @name: String
+    @currency: String
+    @merchant_code: String?
     @no_url_parse: bool
     @params: Hash[Symbol, String]
 
     attr_reader params: Hash[Symbol, String]
+    attr_reader no_url_parse: bool
+
+    def self.generate_reference: (?String prefix) -> String
+
+    def initialize: (
+      upi_id: String,
+      name: String,
+      ?currency: String,
+      ?merchant_code: String?,
+      ?no_url_parse: bool
+    ) -> void
 
-    def generate_qr: -> String
+    def upi_content: (
+      ?amount amount,
+      ?String? note,
+      ?transaction_ref_id: String?,
+      ?transaction_id: String?,
+      ?url: String?,
+      ?min_amount: amount,
+      ?initiation_mode: String?
+    ) -> String
 
-    def upi_content: -> String
+    def generate_qr: (
+      ?amount amount,
+      ?String? note,
+      ?transaction_ref_id: String?,
+      ?transaction_id: String?,
+      ?url: String?,
+      ?min_amount: amount,
+      ?initiation_mode: String?,
+      ?mode: Symbol,
+      ?level: Symbol,
+      **untyped render_options
+    ) -> String
 
     private
 
-    def generate_transaction: -> Hash[Symbol, String]
+    def build_fields: (amount, String?, String?, String?, String?, amount, String?) -> fields
+    def require_reference!: (String?, String?) -> void
+    def validate_vpa!: (String) -> String
+    def validate_text!: (String?, Symbol, String) -> String?
+    def validate_currency!: (String) -> String
+    def validate_merchant_code!: (String?) -> String?
+    def validate_reference!: (String?, Symbol, String) -> String?
+    def validate_url!: (String?) -> String?
+    def validate_initiation_mode!: (String?) -> String?
+    def normalize_min_amount: (amount, String?) -> String?
+    def normalize_amount: (amount, String) -> String?
+    def to_decimal: (untyped, String) -> BigDecimal
+    def presence: (String?) -> String?
+    def encode: (untyped, ?lenient: bool) -> String
+    def render_svg: (untyped, Hash[Symbol, untyped]) -> String
+    def render_png: (untyped, Hash[Symbol, untyped]) -> String
   end
 end

data/upi.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'lib/upi/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'upi'
+  spec.version = Upi::VERSION
+  spec.authors = ['Faraz Noor']
+  spec.email = ['faraznoor75@gmail.com']
+
+  spec.summary = 'Generate UPI codes for payments.'
+  spec.description = 'This gem generates UPI QR codes for payments. It can be used in e-commerce applications to generate QR codes for payments. The QR codes can be scanned by UPI apps to make payments. The gem uses the rqrcode gem to generate the QR codes.'
+  spec.homepage = 'https://github.com/stingrayzboy/upi'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 2.6.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = 'https://github.com/stingrayzboy/upi'
+  spec.metadata['source_code_uri'] = 'https://github.com/stingrayzboy/upi'
+  spec.metadata['changelog_uri'] = 'https://github.com/stingrayzboy/upi/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_runtime_dependency 'chunky_png'
+  spec.add_runtime_dependency 'rqrcode', '2.2.0'
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: upi
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 3.0.0
 platform: ruby
 authors:
 - Faraz Noor
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-08 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chunky_png
@@ -67,6 +67,7 @@ files:
 - lib/upi/version.rb
 - sig/upi.rbs
 - sig/upi/generator.rbs
+- upi.gemspec
 homepage: https://github.com/stingrayzboy/upi
 licenses:
 - MIT
@@ -90,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Generate UPI codes for payments.