qrplatba

Generate Czech 🇨🇿 SPAYD payment QR codes — from an account number to a scannable code in one call.

▶ Live demo

Features

• 🏦 Derives the IBAN from a Czech account number (with prefix and bank code) automatically.
• 🧾 Builds spec-compliant SPAYD content (SPD*1.0*…) per qr-platba.cz.
• 🖼️ Renders to SVG, a data URL, or the raw payload string.
• ⚙️ Optional fields: variable/specific/constant symbols, message, due date, currency, CRC32.
• 🪶 Tiny footprint — a single runtime dependency (qrcode-generator).
• 🟦 Written in TypeScript with full type definitions.

Installation

npm install qrplatba
# or
yarn add qrplatba
# or
bun add qrplatba

Quick start

import { QRPayment } from 'qrplatba';

const qrPayment = new QRPayment(322.4, '19-2000145399/0800', {
  VS: '126303', // Variable symbol
  message: 'Payment for order #126303', // Note (max 60 chars)
});

qrPayment.getSvg(); // <svg …> markup as a string
qrPayment.getDataUrl(); // data:image/gif;base64,… URL
qrPayment.getQrContent(); // SPD*1.0*ACC:CZ65…*CC:CZK*AM:322.40*MSG:…*X-VS:126303

You can pass the account as an object instead of a string:

const qrPayment = new QRPayment(322.4, {
  prefix: '19',
  number: '2000145399',
  bankCode: '0800',
});

Pass null as the amount to omit the AM field (e.g. for an open-amount payment).

Helper functions

If you don't need the instance, the one-shot helpers do the same in a single call:

import { createQrPaymentSvg, createQrPaymentDataUrl, createQrPaymentContent } from 'qrplatba';

createQrPaymentSvg(322.4, '19-2000145399/0800', { VS: '126303' }); // SVG string
createQrPaymentDataUrl(322.4, '19-2000145399/0800', { VS: '126303' }); // data URL
createQrPaymentContent(322.4, '19-2000145399/0800', { VS: '126303' }); // raw SPAYD string

API

new QRPayment(amount, account, options?)

| Argument | Type | Description | | --- | --- | --- | | amount | number \| null | Amount in the chosen currency. null omits the AM field. | | account | string \| Account | Account string ("19-2000145399/0800") or { prefix, number, bankCode }. | | options | PaymentOptions | See the Options table below. |

Instance methods: getSvg(), getDataUrl(), getQrContent(). Instance properties: account, payment, paymentOptions (the validated, normalized values).

Options

| Option | Type | Description | | ---------- | --------- | --------------------------------------------------------------------- | | message | string | Payment note (MSG). Maximum 60 characters; * and % are encoded. | | currency | string | ISO 4217 currency code (CC). Defaults to CZK. | | DT | string | Due date (DT) in YYYYMMDD format. | | VS | string | Variable symbol (X-VS). Up to 10 digits. | | SS | string | Specific symbol (X-SS). Up to 10 digits. | | KS | string | Constant symbol (X-KS). Up to 10 digits. | | URL | string | URL (X-URL). Up to 140 characters. | | crc32 | boolean | When true, appends a CRC32 checksum field to the payload. |

Validation

Invalid input throws a ValidationError (exported from the package) with a descriptive message:

import { ValidationError } from 'qrplatba';

try {
  createQrPaymentContent(100, '19-2000145399/0800', { DT: '2024-01-01' });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error(err.message); // "DT has to be a valid date in YYYYMMDD format"
  }
}

Specification & disclaimer

The generated content follows the format described at qr-platba.cz. This package was primarily built for personal use cases and may not cover every scenario. While efforts have been made to ensure compatibility, you are responsible for verifying the correctness of the generated QR codes for your own accounts.

Development

This project uses Bun.

bun install      # install dependencies
bun run test     # run the test suite
bun run build    # compile TypeScript to dist/
bun run lint     # check formatting with Prettier

The live demo lives in docs/ and is published to GitHub Pages from the main branch.

Issues

Found a problem or have a suggestion? Please open an issue.

License

MIT