kosova-qr-code

Zero-dependency reference library for Kosovo (BQK) payment QR codes — the national profile of the European EPC QR standard adopted by the Central Bank of Kosovo (Banka Qendrore e Republikës së Kosovës).

encode structured input into a canonical QR URL, decode a QR URL back into its parts, and validate any payload against the BQK spec.

Install

npm install kosova-qr-code

ESM-only. Requires a modern Node.js (≥ 18) or bundler.

Usage

import { encode, decode, validate } from "kosova-qr-code";

// Build a canonical QR URL from structured input
const url = encode({
  domain: "xyz.qrc.bqk-kos.org", // H01 — BQK-issued for live use
  type: "i",                     // H03 — invoice / bill payment
  providerId: "ABC",             // H04 — BQK-issued 3-char provider id
  fields: {
    // payload field ids -> raw (un-encoded) values
  },
});

// Parse a QR URL back into its parts
const parsed = decode(url);
console.log(parsed.domain, parsed.version, parsed.type, parsed.fields);

// Validate a URL (or an already-parsed object) against the spec
const result = validate(url);
if (!result.valid) {
  for (const issue of result.issues) {
    console.log(issue.severity, issue.code, issue.message);
  }
}

API

• encode(input: EncodeInput): string — structured input → canonical QR URL string.
• decode(raw: string): ParsedQr — QR URL string → structured parts and fields.
• validate(input: string | ParsedQr): ValidationResult — coded errors + warnings against the BQK spec.

The spec field table is exported as data (FIELDS, FIELD_BY_ID, CANONICAL_ORDER, KNOWN_VERSIONS, KNOWN_TYPES, …) and is the single source of truth for validation. Helpers percentEncode / percentDecode, checkIban / mod97, and checkAmountFormat / isZeroAmount are also exported.

⚠️ Two values you cannot self-assign

The domain subdomain (xxx.qrc.bqk-kos.org) and the 3-char provider ID are issued by BQK to a licensed PSP. A QR built by a third party is spec-shaped but needs a real BQK-issued domain + provider ID (via a partner bank/PSP) to be live-payable. This library gets the format exactly right; the BQK-issued values come from your PSP.

License

MIT © Albin Idrizaj