Standards/hub3
HUB3
Overview
HUB3 is the Croatian standard for encoding payment slip data into a PDF417 2D barcode. It is published by the Croatian Banking Association (HUB) and has been in production use on the HUB-3A national payment form since 4 June 2012 [1]. Every major Croatian bank's mobile app supports scanning HUB3 barcodes to auto-populate transfer forms.
History
A 2011 reform required Croatian payment forms to adopt the international IBAN account format, which broke the data layout of the previous HUB1 2D barcode. The Croatian National Bank's Decision on Payment Orders (NN 3/2011) accompanied the new Payment Transactions Act (Zakon o platnom prometu) that took effect on 1 January 2011 [1]. The Croatian Banking Association issued the HUB3 specification on a new HUB-3A form to carry the IBAN-based data, with version 5 of the spec dated October 2012 [1]. HUB1 use was discontinued on 1 June 2013 [1].
The transition from HRK to EUR on 1 January 2023 did not change the barcode format — only the currency field value [8].
Technical specification
HUB3 mandates a specific PDF417 configuration [1]:
| Parameter | Value |
|---|---|
| Module width (X-dimension) | 0.254 mm (10 mil) |
| Aspect ratio (height : width) | 3 : 1 |
| Error correction level | 4 |
| Data columns | 9 |
| Encoding mode | Binary |
| Compact PDF417 (truncated) | Not used |
| Macro PDF417 (distributed) | Not used |
| Resulting barcode width | 58 mm |
| Max barcode height (with quiet zones) | 26 mm |
The payload is UTF-8 encoded and contains 14 newline-separated fields in this exact order [1]:
| # | Field | Notes |
|---|---|---|
| 1 | Header (HRVHUB30) |
Identifies the format |
| 2 | Currency | 3 chars, e.g. EUR |
| 3 | Amount | 15 chars, zero-padded, in cents (no decimal) |
| 4 | Payer name | up to 30 chars |
| 5 | Payer address (street + number) | up to 27 chars |
| 6 | Payer city (postcode + city) | up to 27 chars |
| 7 | Recipient name | up to 25 chars |
| 8 | Recipient address (street + number) | up to 25 chars |
| 9 | Recipient city (postcode + city) | up to 27 chars |
| 10 | Recipient IBAN or account | 21 chars for Croatian IBAN |
| 11 | Reference model | 4 chars, e.g. HR01, HR00 |
| 12 | Reference number | up to 22 chars |
| 13 | Purpose code | 4-char SEPA code, e.g. COST, GDDS |
| 14 | Payment description | up to 35 chars |
Field lengths are counted in characters, not bytes — the Croatian diacritics č, ć, đ, š, ž (and uppercase) occupy two bytes each in UTF-8, which matters for downstream library implementations [1].
The underlying pdf417 symbology supports up to 925 codewords per symbol, equivalent to ~1850 alphanumeric characters, ~2710 digits, or 1108 bytes [1] — HUB3 payloads are well below this ceiling.
Use cases
The primary use is printed payment slips ("uplatnica") for the Croatian domestic payment system, scanned by bank tellers and customers [1]. Croatian household billing relies heavily on the uplatnica format: every monthly utility statement traditionally ships with one in the same envelope as the bill [14].
Concrete deployment domains [14, hub3-cro]:
- Electricity — the state-run distributor HEP Elektra issues HUB3-bearing uplatnice with semi-annual averaging adjustments; the worked example in
HR-croatia.mdshows a HEP ELEKTRA payment to IBAN HR1234… forPLAĆANJE ELEKTRIČNE ENERGIJE(electricity payment) [hub3-cro]. - Water and waste — water bills and Čistoća municipal-waste invoices use HUB3 uplatnica on monthly cadence, with the amount varying by metered usage [14].
- Telecoms — phone, internet and TV invoices (Hrvatski Telekom, A1, Telemach, et al.) issue HUB3 uplatnica monthly [14].
- Government services and tax — institutional invoices that "you can't physically visit" — local-government fees, university tuition, court filing fees and similar — are delivered as HUB3 uplatnice [14].
- Building maintenance (pričuva) and HOA / association dues —
hrvach/uplatnicaoriginated as a tool for emitting these specific recurring building-maintenance bills [5]. - Donations and charity — printed and online HUB3 slips are a standard way to collect church and NGO donations.
- Mobile-banking scan-to-pay — every major Croatian bank's app supports HUB3 scanning to auto-populate transfer fields:
- Zagrebačka banka (m-zaba) — camera scans the 2D code "after which the payment order is automatically filled out, saving time by eliminating the need to manually enter data from the payment slip" [15].
- PBZ, Erste George (native HUB3 scanner alongside eRačun e-invoice support and ePregled tax integrations), OTP, HPB, Raiffeisen — all ship HUB3 scanning as a standard mobile-banking feature.
- E-commerce checkout via WordPress plugins like WSB HUB3 (and the equivalent
zeko868/Croatian-payment-slip-generator-for-WooCommerce) that generate a printable / on-screen HUB3 slip after order placement [branahr]. - Mass invoicing tooling — open-source generators (
hrvach/uplatnica, the Big Fish Software hosted API) emit print-ready uplatnica PDFs at scale for utility billers and large invoice runs [5, 7].
Implementations
A mature ecosystem of HUB3 encoders exists across languages; PDF417 decoding is handled by general-purpose libraries.
Encoders (HUB3-aware or HUB3-friendly):
- JavaScript (browser + Node) — pkoretic/pdf417-generator — 48★. Provides a
HUB3.format()helper that takes structured{amount, sender, receiver, purpose, description}and emits the 14-field payload, then renders to canvas [2]. - Python — ihabunek/pdf417-py — 98★, last commit 2024. General-purpose PDF417 encoder with command-line and library API; supports Macro PDF417 for very large payloads (not used by HUB3 itself) [3].
- PHP — leongrdic/php-pdf417-hub3 — 2★, 2023. Thin HUB3 wrapper around the upstream
ihabunek/pdf417-phplibrary [4]. - Python + PostScript — hrvach/uplatnica — 112★, 2016. Generates the full uplatnica PDF (form + barcode), not just the bare barcode [5].
Decoders:
- Java + many ports — zxing/zxing — 34,000★, actively maintained in 2025. The de-facto open-source 1D/2D barcode reader; PDF417 is in its supported-formats list [6].
- Honeywell and Zebra hardware scanners ship with HUB3-aware firmware profiles for Croatian banking environments.
Hosted API: hub3.bigfish.software (operated by Big Fish Software, code at git.sr.ht/~ihabunek/hub3-api) — a public REST API that returns a HUB3 PDF417 PNG from a JSON payment payload [7].
Comparison
vs. HUB1 (predecessor, 2009–2013) — HUB1 used the older account-number format (7-digit bank code + 10-digit account); HUB3 carries the international IBAN required after Croatia's 2011 payment-system reform [1]. HUB1 was retired on 1 June 2013 [1].
vs. EPC QR Code (European alternative, ISO/IEC 18004 QR) — The pan-European epc-qr standard for SEPA credit transfers uses a QR code instead of PDF417, and has a different field structure (no separate "model" code and a different reference convention). Croatian banks support EPC QR for cross-border SEPA payments but continue to mandate HUB3 for domestic slips — the model + reference-number convention used in Croatia is not directly representable in EPC QR's payload [hub3-cro].
vs. swiss-qr-bill (Switzerland) — Switzerland replaced its red/orange paper-slip system with the Swiss QR-bill (QR-Rechnung) in 2020, also a national payment-slip format with strict layout rules and a 2D code. The Swiss version chose QR Code with a 7 mm Swiss cross overlay (intentionally violating ISO/IEC 18004 quiet-zone rules), where Croatia chose PDF417 for 2012 hardware reasons; both retain a strong country-specific "look" and reference-number scheme rather than adopting EPC QR wholesale.
vs. upn-qr (Slovenia) — Slovenia's UPN QR (universal payment order) plays the same domestic-payment-slip role as HUB3 in a directly-neighbouring market, but uses a QR code from the start and was rolled out in 2014, two years after HUB3 — a useful contrast on national-symbology choices made within a 24-month window in the same SEPA region [hub3-cro].
Why PDF417 instead of QR for HUB3? The HUB3 specification predates widespread smartphone QR scanning and was designed with larger, more forgiving modules so that inexpensive bank-counter scanners could read it from photocopied or smudged slips [1].
Fun facts
The 2012 spec explicitly designed for smartphone cameras. The HUB3 spec says it widened the module size from HUB1 specifically so that smartphone cameras could read the barcode, not just dedicated bank-counter scanners: "the size of the basic element was increased ... which makes it possible to read (with appropriate application) via smartphones and other devices with built-in cameras" [1, free translation from Croatian]. This is a 2012 design choice that anticipated and arguably enabled the mobile-banking-app scanning workflow now used by every Croatian bank — including a documented 3.2-megapixel-autofocus camera baseline in the spec [14].
Currency-agnostic payload survived the euro changeover. Croatia adopted the euro on 1 January 2023, replacing HRK. HUB3 needed no format change — billers simply switched field 2 from HRK to EUR and reprinted slips. The same barcode generators kept working unmodified, an unusually clean migration in payment-instrument terms [8].
One worked example shipped in the spec is now a meme. The canonical HUB3 example payload — HEP ELEKTRA D.O.O. paying PLAĆANJE ELEKTRIČNE ENERGIJE from IVAN HORVAT of ILICA 1, ZAGREB — appears in the official HUB documentation and is copied across virtually every implementation tutorial and library README in the ecosystem, making HEP-Elektra Croatia's de-facto standard "lorem ipsum" for payment data [hub3-cro].
Croatian uplatnica is the standard SEPA-data-entry shortcut. Multiple Croatian banks let users scan a HUB3 slip and then re-export the pre-filled SEPA fields into a different bank-transfer flow — i.e. HUB3 has been retrofitted as a SEPA-fields data-entry serialization format that happens to be backed by a printed slip in your hand [15].
Status
Active and mandated. HUB3 remains the canonical 2D barcode for Croatian domestic payment slips as of 2026. Recent payment-system changes have all happened around the format rather than replacing it:
- 1 January 2023: HRK → EUR currency transition; HUB3 payloads simply switched from
HRKtoEURin field 2 [8]. - October 2020: launch of EuroNKSInst, Croatia's national instant-payment system operated by FINA, integrated with the pan-European TIPS in June 2023 [9].
- 9 January 2025: all Croatian PSPs required to receive SEPA instant payments; 9 October 2025: required to send [10, 11].
- 1 September 2025: new Fiscalization Act adds JIR/ZKI codes (and a QR code) to consumer receipts — a separate stream from HUB3 payment slips [12].
No successor or deprecation notice has been issued by the Croatian Banking Association.
Sources
- Format zapisa PDF417 2D bar-koda prema HUB3 standardu, v5 — Croatian Banking Association (HUB), October 2012. Primary spec.
- pkoretic/pdf417-generator — JavaScript HUB3 encoder.
- ihabunek/pdf417-py — Python PDF417 encoder, supports Macro PDF417.
- leongrdic/php-pdf417-hub3 — PHP HUB3 wrapper.
- hrvach/uplatnica — Python + PostScript uplatnica generator.
- zxing/zxing — Java 1D/2D barcode reader, PDF417-capable.
- HUB3 Barcode API — Big Fish Software — public REST API.
- The Croatian payment landscape — European Payments Council.
- EuroNKSInst — FINA (Croatian Financial Agency).
- SEPA instant payments introduced in Croatia — Trade Finance Global.
- Croatia to introduce 10-second bank transfers under new rules — Croatia Week.
- Croatia's New Fiscalization Act Explained — RTC Suite.
- WSB HUB3 plugin — WooCommerce HUB3 generator.
- How to pay bills in Croatia (invoices, račun) — Expat In Croatia
- m-zaba mobile banking — Zagrebačka banka
- HR-croatia.md — internal country report.
Deployments
Found in the following country reports (grep across reports/countries/):
- HR — HR-croatia.md
- IE — IE-ireland.md