Skip to content

typescript

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

typescript

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 
bun.lock
bun.lock
 
 
bunfig.toml
bunfig.toml
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

bysquare

"PAY by square" is a national standard for QR code payments that was adopted by the Slovak Banking Association in 2013. It is incorporated into a variety of invoices, reminders and other payment regulations.

Features • Installation • Usage • CLI • Validation

Features

  • TypeScript support
  • CLI tooling
  • Compatible with Slovak banking apps
  • Isomorphic Browser & Runtime-independent (Browser, Node.js, Bun, Deno)

Note

Since v3, the implementation is considered stable and specification-complete.
No breaking changes are planned. Only minor improvements and bug fixes may be introduced.

Installation

npm

$ npm install bysquare

browser

<script type="module">
// payments
import {
	decode,
	encode,
} from "https://esm.sh/bysquare@4/pay";

// invoices
import {
	decode,
	encode,
} from "https://esm.sh/bysquare@4/invoice";
</script>

Usage

This library provides encode and decode functions to work with the data model directly, allowing you to create customized payment solutions.

Pay BySquare

HTML example

This example shows how to generate a payment QR code and display it in a web page:

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<title>Payment QR Code</title>
	</head>
	<body>
		<div
			id="qrcode"
			style="width: 200px"
		/>

		<script type="module">
		import { QRCode } from "https://esm.sh/@lostinbrittany/qr-esm@latest";
		import {
			CurrencyCode,
			encode,
			PaymentOptions,
		} from "https://esm.sh/bysquare@4/pay";

		const qrstring = encode({
			payments: [
				{
					type: PaymentOptions.PaymentOrder,
					amount: 123.45,
					variableSymbol: "987654",
					currencyCode: CurrencyCode.EUR,
					beneficiary: { name: "John Doe" },
					bankAccounts: [{ iban: "SK9611000000002918599669" }],
				},
			],
		});

		const qrElement = document.getElementById("qrcode");
		qrElement.appendChild(QRCode.generateSVG(qrstring));
		</script>
	</body>
</html>
Creating Payment QR Codes

To generate QR codes for different payment types, use the encode function with the appropriate payment configuration:

import {
	CurrencyCode,
	encode,
	Month,
	PaymentOptions,
	Periodicity,
} from "bysquare/pay";

// Simple Payment (Payment Order)
const qrstring = encode({
	payments: [
		{
			type: PaymentOptions.PaymentOrder, // 1
			amount: 50.75,
			variableSymbol: "123456",
			currencyCode: CurrencyCode.EUR, // "EUR"
			beneficiary: { name: "John Doe" },
			bankAccounts: [{ iban: "SK9611000000002918599669" }],
		},
	],
});

// Standing Order
const qrstring = encode({
	payments: [
		{
			type: PaymentOptions.StandingOrder, // 3
			amount: 100.0,
			variableSymbol: "654321",
			currencyCode: CurrencyCode.EUR, // "EUR"
			day: 15,
			month: Month.January, // Single month
			periodicity: Periodicity.Monthly, // "m"
			beneficiary: { name: "John Doe" },
			bankAccounts: [{ iban: "SK9611000000002918599669" }],
		},
	],
});

// Direct Debit
const qrstring = encode({
	payments: [
		{
			type: PaymentOptions.DirectDebit, // 2
			amount: 25.0,
			variableSymbol: "789012",
			currencyCode: CurrencyCode.EUR, // "EUR"
			beneficiary: { name: "John Doe" },
			bankAccounts: [{ iban: "SK9611000000002918599669" }],
		},
	],
});
Standing Order with Multiple Months

For standing orders that should execute in specific months, you can combine multiple months using bitwise OR operators:

import { encodeOptions } from "bysquare";
import {
	CurrencyCode,
	encode,
	Month,
	PaymentOptions,
	Periodicity,
} from "bysquare/pay";

const qrstring = encode({
	payments: [
		{
			type: PaymentOptions.StandingOrder,
			amount: 100.0,
			variableSymbol: "654321",
			currencyCode: CurrencyCode.EUR,
			day: 15,
			// Execute in January, July, and October only
			month: Month.January | Month.July | Month.October, // Results in 577
			periodicity: Periodicity.Monthly,
			lastDate: "20251231",
			beneficiary: { name: "John Doe" },
			bankAccounts: [{ iban: "SK9611000000002918599669" }],
		},
	],
});

// Alternative: Use the utility function to encode multiple months
const monthsToEncode = [Month.January, Month.July, Month.October];
const encodedMonths = encodeOptions(monthsToEncode);

const qrstring2 = encode({
	payments: [
		{
			type: PaymentOptions.StandingOrder,
			amount: 100.0,
			variableSymbol: "654321",
			currencyCode: CurrencyCode.EUR,
			day: 15,
			month: encodedMonths, // Same result: 577
			periodicity: Periodicity.Monthly,
			lastDate: "20251231",
			beneficiary: { name: "John Doe" },
			bankAccounts: [{ iban: "SK9611000000002918599669" }],
		},
	],
});

[!NOTE] Date Format: Provide date inputs (e.g., paymentDueDate, lastDate) in ISO 8601 format (YYYY-MM-DD). They are automatically converted to YYYYMMDD during encoding to match the Pay by Square specification.

Advanced usage

For more complex data with multiple payments and additional fields:

[!NOTE] Encoded data are without diacritics

The library removes all diacritics from the input data to ensure maximum compatibility, as not all banks support diacritics, which may lead to errors. If you need to retain diacritics, disable deburr option when encoding data - encode(model, { deburr: false }).

import {
	CurrencyCode,
	type DataModel,
	decode,
	encode,
	PaymentOptions,
} from "bysquare/pay";

const data = {
	invoiceId: "random-id",
	payments: [
		{
			type: PaymentOptions.PaymentOrder,
			currencyCode: CurrencyCode.EUR,
			amount: 100.0,
			variableSymbol: "123",
			paymentNote: "hello world",
			beneficiary: { name: "John Doe" },
			bankAccounts: [
				{ iban: "SK9611000000002918599669" },
				// ...more bank accounts
			],
			// ...more fields
		},
		// ...more payments
	],
} satisfies DataModel;

// Encode data to a QR string
const qrstring = encode(data);

// Decode QR string back to the original data model
const model = decode(qrstring);

Invoice BySquare

In addition to PAY by square (payment QR codes), this library supports encoding and decoding invoice documents (bysquareType=1). The invoice implementation was reverse-engineered from the official Android application.

HTML example

This example shows how to generate an invoice QR code and display it in a web page:

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<title>Invoice QR Code</title>
	</head>
	<body>
		<div
			id="qrcode"
			style="width: 200px"
		/>

		<script type="module">
		import { QRCode } from "https://esm.sh/@lostinbrittany/qr-esm@latest";
		import {
			encode,
			InvoiceDocumentType,
		} from "https://esm.sh/bysquare@4/invoice";

		const qrstring = encode({
			documentType: InvoiceDocumentType.Invoice,
			invoiceId: "FV2024001",
			issueDate: "20240115",
			localCurrencyCode: "EUR",
			supplierParty: {
				partyName: "Supplier s.r.o.",
				postalAddress: {
					streetName: "Hlavna",
					cityName: "Bratislava",
					postalZone: "81101",
					country: "SVK",
				},
			},
			customerParty: {
				partyName: "Customer a.s.",
			},
			numberOfInvoiceLines: 1,
			taxCategorySummaries: [{
				classifiedTaxCategory: 0.2,
				taxExclusiveAmount: 100,
				taxAmount: 20,
			}],
			monetarySummary: {},
		});

		const qrElement = document.getElementById("qrcode");
		qrElement.appendChild(QRCode.generateSVG(qrstring));
		</script>
	</body>
</html>
Invoice Document Types
Type Code Description
Invoice 0 Standard invoice
ProformaInvoice 1 Proforma (advance) invoice
CreditNote 2 Credit note (reversal)
DebitNote 3 Debit note
AdvanceInvoice 4 Advance invoice
Encode Invoice 
import {
	type DataModel,
	encode,
	InvoiceDocumentType,
} from "bysquare/invoice";

const invoice: DataModel = {
	documentType: InvoiceDocumentType.Invoice,
	invoiceId: "FV2024001",
	issueDate: "20240115",
	localCurrencyCode: "EUR",
	supplierParty: {
		partyName: "Supplier s.r.o.",
		postalAddress: {
			streetName: "Hlavna",
			cityName: "Bratislava",
			postalZone: "81101",
			country: "SVK",
		},
	},
	customerParty: {
		partyName: "Customer a.s.",
	},
	numberOfInvoiceLines: 3,
	taxCategorySummaries: [{
		classifiedTaxCategory: 0.2,
		taxExclusiveAmount: 100,
		taxAmount: 20,
	}],
	monetarySummary: {},
};

const qr = encode(invoice);
Decode Invoice 
import { decode } from "bysquare/invoice";

const invoice = decode(qr);

console.log(invoice.invoiceId);
console.log(invoice.documentType);
console.log(invoice.supplierParty.partyName);
Invoice Validation

encode validates the data model by default. Key validation rules:

  • invoiceId and issueDate are required
  • localCurrencyCode must be a 3-letter uppercase code (ISO 4217)
  • Foreign currency fields (foreignCurrencyCode, currRate, referenceCurrRate) must all be present or all absent
  • Supplier party requires partyName and postal address with streetName, cityName, postalZone, and country
  • Customer party requires partyName
  • Exactly one of numberOfInvoiceLines or singleInvoiceLine must be set
  • At least one tax category summary is required with classifiedTaxCategory in range [0, 1]

Validation can be disabled:

const qr = encode(invoice, { validate: false });

Classifier Utilities

The library provides utility functions for working with multiple classifier options as specified in the PAY by Square standard. These functions are particularly useful for handling multiple month selections in standing orders.

Encoding Multiple Options

import { encodeOptions } from "bysquare";
import { Month } from "bysquare/pay";

// Encode multiple months into a single value
const monthsArray = [Month.January, Month.July, Month.October];
const encoded = encodeOptions(monthsArray);
console.log(encoded); // 577 (1 + 64 + 512)

// This matches the specification example:
// January=1, July=64, October=512, sum=577

CLI

$ npm install --global bysquare

PAY

$ bysquare pay encode [OPTIONS] file1.json file2.json...
$ bysquare pay encode file.jsonl
$ bysquare pay decode <qrstring>

Invoice

$ bysquare invoice encode [OPTIONS] invoice.json
$ bysquare invoice decode <qrstring>

Auto-detect Decode

Decode any BySquare QR string by auto-detecting the type from the header.

$ bysquare decode <qrstring>

Validation

This library uses permissive validation to ensure maximum compatibility with various Slovak banking applications. The validation does not strictly enforce all XSD schema restrictions.

Validation Behavior

Aspect Behavior
IBAN Validated (format + checksum via ISO 13616)
BIC Validated (format via ISO 9362)
Currency Validated (ISO 4217, case-insensitive, includes XXX)
Date Validated (ISO 8601 format)
Beneficiary name Required (per spec v1.2.0)
Symbols Permissive (accepts letters, spaces - XSD pattern not enforced)
Amounts Permissive (accepts negative values)
Field lengths Not enforced

XSD Field Constraints Reference

https://www.bsqr.co/schema/

For reference, the official XSD schema defines these constraints (not enforced by this library):

Field Max Length Pattern
variableSymbol 10 [0-9]{0,10}
constantSymbol 4 [0-9]{0,4}
specificSymbol 10 [0-9]{0,10}
paymentNote 140 -
originatorsReferenceInformation 35 -
invoiceId 10 -
beneficiary.name 70 -
beneficiary.street 70 -
beneficiary.city 70 -
mandateId 35 -
creditorId 35 -
contractId 35 -
amount 15 >= 0