Standards/pay-by-square
PAY by square
Overview
PAY by square is the Slovak payment-QR standard: a QR Code (QR Code 2005) whose content is a compressed, alphanumeric-encoded payment order that a mobile banking app scans to pre-fill a transfer 1. It was adopted by the Slovak Banking Association (Slovenská banková asociácia, SBA) in 2013 5, is published by the SBA under a free, royalty-free licence 2, and is described as "the standard of Slovak banks" for encoding payment data 3. Unlike text-based payment QR formats, the payload is a tab-separated field sequence, prefixed with a CRC32 checksum, LZMA-compressed, given a 4-nibble header, and encoded with Base32hex so it fits QR alphanumeric mode 1.
History
The SBA's licence terms state that the SBA — whose remit includes implementing SEPA in Slovakia — wanted a payment-QR standard that all businesses and consumers could use free of charge, and that it developed PAY by square together with its member banks and Forsys a.s., a company specialising in process digitisation 2. The specification itself names ADELANTE, s.r.o. (Bratislava) as the company "developing, publishing, promoting and aiding implementation of the PAY by square standard for the benefit of the SBA", and "by square" is an ADELANTE trademark 13. (The two SBA-hosted documents thus credit different companies; neither explains the relationship.)
Milestones from the specification's version history and related records:
- 22 February 2013 — PAY by square specification document version 0 created "from original by square specifications" 1.
- 2013 — standard adopted by the SBA 5; ADELANTE's by square iOS app version 1.0 released 10 May 2013 4.
- 24 June 2015 — specification revision adds beneficiary name and address fields (schema 1.1.0); these were appended at the end of the sequence to keep bulk-payment readers backward compatible 1.
- 1 April 2025 — specification 1.2.0: beneficiary name becomes a required field 1.
Technical specification
Symbology: QR Code 2005 (ISO/IEC 18004), encoded in Alphanumeric mode, QR versions 1–17 at error-correction level L ("xL") 1.
Encoding pipeline (section 3 of the spec) 1:
- Client data is modelled as an XML document validated by the by square XSD schema. Dates are converted from
YYYY-MM-DDtoYYYYMMDD; amounts use.as decimal mark; currency is ISO 4217 (3 letters), country ISO 3166 alpha-3, BIC per ISO 9362, IBAN per ISO 13616. Multi-option fields (e.g. months, payment options) are stored as the sum of power-of-two classifiers (January=1 … December=2048; paymentorder=1, standingorder=2, directdebit=4). - Field sequence — values are concatenated in XSD order separated by the ASCII horizontal tab; tabs inside values are replaced by spaces; missing optional fields become empty strings (consecutive tabs). Repeating elements (e.g.
BankAccounts) are preceded by a count; optional complex elements (StandingOrderExt,DirectDebitExt) by0/1. - Length limit — for QR use the sequence is capped at 550 UTF-8 characters (including tabs), enough for up to 5 payment orders with multiple accounts; for non-QR uses the limit is 65,535 compressed bytes.
- CRC32 of the sequence is prepended (4 bytes, little-endian).
- LZMA compression with lc=3, lp=0, pb=2, dictionary 128 KiB (2^17); the standard LZMA header is replaced by a 2-byte little-endian word holding the uncompressed size.
- Header — four 4-bit fields:
BySquareType,Version,DocumentType,Reserved. PAY by square is type0000, document type0000(PAY). - Base32hex — bits are padded to a multiple of 5 and mapped to
0-9A-V(RFC 4648 "base32hex" alphabet), a subset of the QR alphanumeric charset. The result is ~10% larger than the binary input and may also be stored as a.bsqrfile or sent over NFC.
An independent implementation documents the resulting wire format as BySquareType(4) | Version(4) | DocType(4) | Reserved(4) | DataLength(16) | LZMA body before Base32hex 5; the Python reference encoder by matusf builds exactly this (header 0x0000, 2-byte length, raw LZMA1 stream, Base32hex alphabet 0123456789ABCDEFGHIJKLMNOPQRSTUV) 6.
Data model (Appendix D, sequence order) 1:
| # | Field | Max len | # | Field | Max len |
|---|---|---|---|---|---|
| 1 | InvoiceID | 10 | 18 | Periodicity (d/w/b/m/B/q/s/a) | 1 |
| 2 | Payments (count) | — | 19 | LastDate | 8 |
| 3 | PaymentOptions | 1 | 20 | DirectDebitExt (0/1) | 1 |
| 4 | Amount | 15 | 21 | DirectDebitScheme (0 other / 1 SEPA) | 1 |
| 5 | CurrencyCode | 3 | 22 | DirectDebitType (0 one-off / 1 recurrent) | 1 |
| 6 | PaymentDueDate | 8 | 23–25 | VariableSymbol, SpecificSymbol, OriginatorsReferenceInformation (DD) | 10/10/35 |
| 7 | VariableSymbol | 10 | 26 | MandateID | 35 |
| 8 | ConstantSymbol | 4 | 27 | CreditorID | 35 |
| 9 | SpecificSymbol | 10 | 28 | ContractID | 35 |
| 10 | OriginatorsReferenceInformation | 35 | 29 | MaxAmount | 15 |
| 11 | PaymentNote | 140 | 30 | ValidTillDate | 8 |
| 12 | BankAccounts (count) | — | 31 | BeneficiaryName (required since 1.2.0) | 70 |
| 13 | IBAN | 34 | 32 | BeneficiaryAddressLine1 | 70 |
| 14 | BIC | 11 | 33 | BeneficiaryAddressLine2 | 70 |
| 15 | StandingOrderExt (0/1) | 1 | |||
| 16 | Day | 2 | |||
| 17 | Month | 4 |
A single code can carry a one-off payment order, a standing order extension and a direct debit extension (SEPA or domestic), and several bank accounts — up to 6 for a simple payment order, with the first treated as the default 1. Payment references can use the Slovak/Czech variable/constant/specific symbols or the SEPA originator's reference 1.
Physical size and branding: recommended size 36 × 36 mm, minimum 30 × 30 mm; every code must carry the PAY by square logo, and codes not generated per the spec must not use it 12.
Decoding: a decoder must reject codes whose header version exceeds its own, and terminates on CRC32 mismatch 1.
Invoice by square
The by square family has other types. INVOICE by square carries general invoice data, a tax recapitulation and one invoiced line item, and is supported by the Slovak Chamber of Certified Accountants (SKCÚ) 3. The xseman implementation encodes it as BySquareType 0x01 with document types Invoice (0x00), Proforma Invoice (0x01), Credit Note (0x02), Debit Note (0x03) and Advance Invoice (0x04), sharing the same wire format and pipeline as PAY by square 5.
Use cases
- Invoices and bills — printed on invoices, reminders and payment requests; e.g. utility company KJG a.s. prints PAY by square codes (IBAN, variable symbol, amount, recipient name) on its invoices 59.
- Post offices — invoices bearing PAY by square can be paid at all Slovak post offices, with payments before 10:00 credited the same business day 3.
- Government fees — the Slovak central public-administration portal slovensko.sk lists PAY by square as an online payment method: scanning the QR code on the payment order transfers the data into the banking app 8.
- Retail point of sale — since 1 May 2026, Act No. 384/2025 Coll. requires sellers to offer a cashless option for purchases over €1; small merchants can generate a PAY by square code in their banking app (or print one without an amount) for customers to scan 7.
- Peer-to-peer — ADELANTE's by square app lets users share bank details as a QR code to receive payments; the spec recommends banking apps also generate codes for P2P use and read codes from PDF/image files 41.
Implementations
| Repo | Language | Kind | Stars | Last push | Notes |
|---|---|---|---|---|---|
| xseman/bysquare | TypeScript + Go | encoder + decoder | 62 | Sep 2026 | Pay v1.1 and v1.2, Invoice by square; C FFI bindings for C#, PHP, Python, Swift, Dart; Apache-2.0 513 |
| RikudouSage/QrPaymentSK | PHP | encoder | 37 | Oct 2025 | "QR payment generator for Slovak banks (the bysquare standard)"; MIT 13 |
| matusf/pay-by-square | Python | encoder | 32 | Jul 2024 | ~100-line stdlib encoder (lzma, binascii.crc32); installable with pip install pay-by-square 6 |
| slatinsky/php-pay-by-square | PHP | encoder | 30 | Sep 2025 | Drop-in PHP microservice generator 13 |
| PavlinII/PayBySquare.TextGenerator.NET | VB.NET | encoder | 15 | Jan 2026 | Text generator for .NET 13 |
Star counts and last-push dates from the GitHub API, 6 October 2026 13. ADELANTE also offers official by square software libraries, test utilities and an implementation manual 1.
Comparison
| PAY by square (SK) | QR Platba / SPAYD (CZ) | EPC QR / Stuzza (EU) | |
|---|---|---|---|
| Payload | Binary: CRC32 + LZMA, Base32hex text 1 | Plain text SPD*1.0*KEY:value*… 11 |
Plain text, newline-separated BCD fields 10 |
| Human-readable after scan | No (must decompress) | Yes | Yes |
| QR mode | Alphanumeric only 1 | Alphanumeric recommended 11 | — |
| Integrity check | Mandatory CRC32 1 | Optional CRC32 field 11 |
none in payload |
| Payment types | Payment order + standing order + direct debit; multiple payments and accounts per code 1 | Single payment | Single SEPA credit transfer 10 |
| National references | Variable/constant/specific symbol 1 | X-VS, X-SS, X-KS 11 |
Structured/unstructured remittance |
| Origin | SBA, 2013 25 | Czech Banking Association, 14 Nov 2012 cz-spayd | STUZZA 2012 → EPC Feb 2013 10 |
Choosing: PAY by square is the format Slovak banking apps read universally 7, so it is the choice for invoices addressed to Slovak payers and for codes that need standing-order or direct-debit setup or multiple payments in one symbol. Its compression keeps rich payloads within a fixed-size symbol 1, at the cost of an implementation that needs LZMA and Base32hex rather than string concatenation. EPC QR is the choice for cross-border euro invoices in the countries that support it 10, and SPAYD for Czech-koruna payments 11. The SBA's licence explicitly does not restrict the use of other payment QR codes in the EEA 2.
Fun facts
- Base32hex output can be saved to a file with the extension
.bsqr("BSQR" being the spec's own abbreviation for a by square QR code) or transmitted via NFC rather than printed 1. - The standard was designed so that a code never exceeds a fixed QR version, letting invoice layouts reserve a fixed 36 mm square regardless of content 1.
Status
Active. Specification 1.2.0 (April 2025) made the beneficiary name mandatory 1. A May 2026 accounting-software guide states that "the Pay-by-square QR code format is supported by all Slovak banks" 7, and the SBA continues to present PAY by square as the QR payment standard it introduced to the Slovak market alongside its separate Payme link format 12. Open-source implementations remain actively maintained in 2026 13.
Sources
1 PAY by square specifications 1.2.0 — ADELANTE, s.r.o. for SBA, accessed 2026-10-06.
2 Podmienky použitia a špecifikácia štandardu „PAY by square“ — Slovenská banková asociácia, accessed 2026-10-06.
3 by square — ADELANTE, s.r.o., accessed 2026-10-06.
4 by square — App Store — Apple / ADELANTE, s.r.o., accessed 2026-10-06.
5 xseman/bysquare README — GitHub, accessed 2026-10-06.
6 matusf/pay-by-square — GitHub (source pay_by_square.py), accessed 2026-10-06.
7 QR platby pri hotovostnom predaji v programe POHODA — STORMWARE s.r.o., updated 18 May 2026, accessed 2026-10-06.
8 Platba online — Ústredný portál verejnej správy (slovensko.sk), accessed 2026-10-06.
9 Payment of an invoice through a QR code (PAY BY SQUARE) — KJG a.s., accessed 2026-10-06.
10 EPC QR code — Wikipedia, accessed 2026-10-06.
11 QR Platba — specifikace formátu — qr-platba.cz, accessed 2026-10-06.
12 Payme — Slovenská banková asociácia, accessed 2026-10-06.
13 GitHub API repository metadata for xseman/bysquare, RikudouSage/QrPaymentSK, slatinsky/php-pay-by-square, matusf/pay-by-square, PavlinII/PayBySquare.TextGenerator.NET — GitHub, accessed 2026-10-06.
Related in-corpus report: QR Platba / SPAYD.
Deployments
Found in the following country reports (grep across reports/countries/):
- SK — SK-slovakia.md