PayQR – IPS QR Code Generator (GUI + CLI)

PayQR generates IPS payment QR codes from a TOML template. You can use a friendly Tkinter GUI or a headless CLI. Templates define the ordered key:value pairs rendered into the QR payload, joined with | (pipe), for example:

K:PR|V:01|C:1|R:123456789012345678|N:Recipient Name|I:RSD1000,00|P:Payment Purpose|SF:123|S:Description

Features

• Template-driven payload (order, defaults, required fields)
• GUI with dynamic form built from the template
  • Template selector to switch between predefined templates
  • Amount field split: currency (read-only) + numeric value
  • Read-only fixed fields (IdentificationCode, Version, CodeSet)
  • Live QR preview at a fixed size
  • Auto-save protection for default template
• CLI to generate QR PNGs from templates

How templates work

A template is a TOML file of ordered field tables, each with a key, a default value, and optional required/pattern. The config.toml holds the fixed IPS fields (K, V, C) plus rendering settings (separator, kv_sep, trim_empty). Fields are merged in order — config fields first, then template fields — and rendered as key:value pairs joined with the separator. Fields with empty values are skipped when trim_empty is set.

User templates in ~/.payqr/templates/ take priority over the bundled templates/ directory, so the GUI only copies bundled templates in on first run.

Setup

# Install dependencies (uv)
uv sync

Requires Python 3.10+. The GUI needs a Python build with Tkinter (the dev env uses 3.13).

Run the GUI

uv run payqr

GUI highlights:

• Select a template from the dropdown menu
• Amount is entered as currency (read-only, e.g., RSD) + numeric value (e.g., 1234,56). The two are combined as I:RSD1234,56 in the payload
• When modifying the default template, you'll be prompted to save as a new template to protect the original
• Templates are automatically saved when you generate a QR code
• Click "Generate" to create and preview the QR code, or "Save as…" to export a PNG

Run the CLI

# Generate a QR using the default template
uv run payqr-cli --out qr.png

# Or specify a template file or name explicitly
uv run payqr-cli --template path/to/template.toml --out qr.png
uv run payqr-cli --template my-template --out qr.png

Tests and linting

uv run pytest            # run the test suite
uv run ruff check .      # lint
uv run ruff format --check .   # check formatting

Both jobs run automatically in CI on every push and pull request.

Build for macOS

bash packaging/macos/build.sh

Produces dist/PayQR.app (GUI app bundle) and dist/payqr-cli (single-file CLI binary) at the repo root using PyInstaller. macOS only.

License

MIT