It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)
"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
[!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.
$ npm install bysquare
<script type="module">
import { encode, decode } from "https://esm.sh/bysquare@4/pay";
</script>
This library provides encode and decode functions to work with the data
model directly, allowing you to create customized payment solutions.
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"></div>
<script type="module">
import { QRCode } from "https://esm.sh/@lostinbrittany/qr-esm@latest";
import { encode, PaymentOptions, CurrencyCode } 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>
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" }],
},
],
});
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 toYYYYMMDDduring encoding to match the Pay by Square specification.
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);
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.
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"></div>
<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>
| 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 |
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);
import { decode } from "bysquare/invoice";
const invoice = decode(qr);
console.log(invoice.invoiceId);
console.log(invoice.documentType);
console.log(invoice.supplierParty.partyName);
encode validates the data model by default. Key validation rules:
invoiceId and issueDate are requiredlocalCurrencyCode must be a 3-letter uppercase code (ISO 4217)foreignCurrencyCode, currRate, referenceCurrRate)
must all be present or all absentpartyName and postal address with streetName,
cityName, postalZone, and countrypartyNamenumberOfInvoiceLines or singleInvoiceLine must be setclassifiedTaxCategory
in range [0, 1]Validation can be disabled:
const qr = encode(invoice, { validate: false });
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.
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
$ npm install --global bysquare
$ bysquare pay encode [OPTIONS] file1.json file2.json...
$ bysquare pay encode file.jsonl
$ bysquare pay decode <qrstring>
$ bysquare invoice encode [OPTIONS] invoice.json
$ bysquare invoice decode <qrstring>
Decode any BySquare QR string by auto-detecting the type from the header.
$ bysquare decode <qrstring>
This library uses permissive validation to ensure maximum compatibility with various Slovak banking applications. The validation does not strictly enforce all XSD schema restrictions.
| 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 |
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 |
FAQs
It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)
The npm package bysquare receives a total of 2,325 weekly downloads. As such, bysquare popularity was classified as popular.
We found that bysquare demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Docker and Socket have uncovered malicious Checkmarx KICS images and suspicious code extension releases in a broader supply chain compromise.
Research
Malicious Namastex.ai npm packages appear to replicate TeamPCP-style Canister Worm tradecraft, including exfiltration and self-propagation.
Product
Explore exportable charts for vulnerabilities, dependencies, and usage with Reports, Socket’s new extensible reporting framework.