Skip to content
barcoder

Standards/poland-ksef-qr

Poland KSeF QR

TypeQR Data Format
PrimaryPL
Completeness81%high

Overview

The KSeF verification QR codes are the QR Code symbols printed on visualisations of invoices from Poland's National e-Invoicing System (Krajowy System e-Faktur, KSeF), run by the Ministry of Finance. Polish law calls them the "kod weryfikujący" and the code proving "authenticity of origin and integrity of content"; the ministry's documentation calls them KOD I and KOD II 1 5.

Each is a URL QR: an https:// link built locally by the invoicing software, not issued by the tax authority 5. KOD I links a printed or PDF invoice to the XML copy in KSeF through its SHA-256 hash. KOD II, used only on offline invoices not yet sent to KSeF, adds a signature that identifies the issuer 4 5. Neither is a payment code 22.

History

  • 16 June 2023. The Act of this date (Dz. U. 2023 poz. 1598) set 1 July 2024 as its main commencement date. It already required a code giving access to the invoice in KSeF and allowing its data to be checked, when a structured invoice is handed over or used outside KSeF (art. 106gb(5) of the VAT Act) 3.
  • October 2023. The training firm Akademia LTCA relayed a reply from KSeF support on an open design problem: an invoice issued offline has no KSeF number yet to link to. Support said detail would follow the implementing regulation 19. The published design links through the invoice hash, seller NIP and date instead 5.
  • December 2023. Per the tax-compliance vendor Sovos, specification 1.5 for the KSeF test environment described the QR codes and verification links and required ISO/IEC 18004:2015 18. The current regulation requires the 2024 edition 1.
  • 9 May 2024. An amending act (Dz. U. 2024 poz. 852) moved the mandatory start to 1 February 2026 15.
  • 5 August 2025. A second amending act (Dz. U. 2025 poz. 1203, published 1 September 2025) created the voluntary offline mode, art. 106nda, and the second code. It also extended the code duty to entities other than the taxpayer 2.
  • 21 August 2025. Date on the KSeF 2.0 QR guide 5.
  • 12 December 2025. The implementing regulation (Dz. U. 2025 poz. 1815, published 18 December 2025) fixed the contents and labels, effective 1 February 2026 1.
  • 1 February 2026. QR codes began to apply in production. Invoices from the earlier voluntary period need not carry them 9.

Technical specification

Property Value
Symbology QR Code, ISO/IEC 18004:2024 1
Payload One HTTPS URL, built locally by the client application 5
Hash SHA-256 of the invoice XML file, Base64URL-encoded (the wyróżnik faktury) 1 4 5
Date format DD-MM-RRRR (day first) 5
Version, error correction, print size Not fixed. The guide's code sample only sets PixelsPerModule = 5 5

Hosts

Environment Host
TE (test) qr-test.ksef.mf.gov.pl
DEMO (pre-production) qr-demo.ksef.mf.gov.pl
PROD qr.ksef.mf.gov.pl

All three are listed in the ministry's guide 5.

KOD I: invoice verification

https://{host}/invoice/{seller NIP}/{date DD-MM-RRRR}/{SHA-256 Base64URL}

The ministry's published sample, on the test host, uses the dummy NIP 1111111111 5. The ministry's one-page summaries list the same elements 6 7:

https://qr-test.ksef.mf.gov.pl/invoice/1111111111/01-02-2026/UtQp9Gpc51y-u3xApZjIjgkpZ01js-J8KflSPW8WzIE

The date is the issue date from field P_1 of the FA(3) structure 4 5. The regulation substitutes the correction date on a corrective invoice 1. On VAT RR invoices for flat-rate farmers, the farmer's NIP takes the seller's place 1. The hash in the sample is 43 characters with no padding, which decodes to 32 bytes.

The text directly under the symbol depends on the invoice's state 1 5:

State Label under KOD I
KSeF number assigned The KSeF number
Not yet sent to KSeF OFFLINE

A KSeF number has 35 characters, NIP-RRRRMMDD-FFFFFFFFFFFF-FF: the seller's NIP, the date, 12 uppercase hexadecimal characters, and a CRC-8 checksum (polynomial 0x07, initial value 0x00) 13.

KOD II: certificate verification (offline only)

https://{host}/certificate/{context type}/{context value}/{seller NIP}/{certificate serial}/{SHA-256 Base64URL}/{signature Base64URL}
  • Context type: Nip, InternalId, NipVatUe or PeppolId 5 14. The context is the identifier of the taxpayer on whose behalf the issuer is authorised 1.
  • Certificate: an active KSeF certificate of type Offline, which the portal calls type 2. An Authentication certificate must not be used 4 5 12. Certificates last at most 2 years 1.
  • Signed string: the URL without https://, up to and including the hash, with no trailing slash. It is hashed with SHA-256 and then signed 5. The ministry's sample on the test host 5:
qr-test.ksef.mf.gov.pl/certificate/Nip/1111111111/1111111111/01F20A5D352AE590/UtQp9Gpc51y-u3xApZjIjgkpZ01js-J8KflSPW8WzIE
  • Signature, RSA: RSASSA-PSS with SHA-256, MGF1 with SHA-256, a 32-byte salt and a key of at least 2048 bits 5.
  • Signature, ECDSA: P-256 with SHA-256. IEEE P1363 output (R || S) is recommended, with ASN.1 DER only where P1363 is technically impossible 5.
  • Encoding: the signature is Base64URL-encoded, and CERTYFIKAT goes directly under the symbol 1 5.

Payload length

By arithmetic on the sample values, assuming an unpadded signature as with the hash: on the production host, KOD I is 99 characters. KOD II is about 211 characters with a P-256 signature (86 characters) and about 467 with RSA-2048 (342 characters). An RSA code is therefore much denser, a consequence the guide does not discuss.

Verification

Scanning needs no KSeF login, only a smartphone 9. It is a two-step design:

  1. KOD I. The scan shows basic identifying data and whether the invoice is in KSeF 4.
  2. Full download. This requires the invoice number, the buyer's identifier (or a statement that there is none) and the gross total 1.

For KOD II, the system checks certificate validity, the signature, the issuer's permissions, and consistency between the context and the seller's NIP 5.

Which codes go where

Invoice Codes Legal basis
Online, or offline already sent to KSeF, used outside KSeF KOD I + KSeF number Reg. § 9(1)–(2) 1
offline24, or offline during unavailability, handed before sending to a buyer listed in art. 106gb(4) KOD I + OFFLINE, and KOD II + CERTYFIKAT Reg. § 9(3), (10) 1; art. 106nda(6) 2
Emergency mode (awaria), handed to any buyer before sending Same two codes Reg. § 9(4), (10) 1
Total outage (awaria całkowita) None KSeF guide 11

The buyers in art. 106gb(4) include foreign buyers, certain EU SME-scheme taxpayers, buyers with no tax number, and consumers 2 3 4. If the invoice format cannot carry a graphic, a separate link or image goes with it, along with the number or label 1.

Submission deadlines differ by mode: next working day for offline24 (art. 106nda(2)), next working day after unavailability ends for offline, and 7 working days after the failure ends for emergency mode 2 8 11.

Use cases

  • Consumer invoices. Issuing these through KSeF is voluntary, but one that is issued there and handed over by PDF or print must carry the code 9.
  • Foreign buyers. Their invoices carry a QR code and the KSeF number, so they can verify them 9.
  • Outage continuity. Two-code invoices can be handed over while KSeF is down 10.
  • Courts and prosecutors. An e-invoice a taxpayer must provide to them, when used outside KSeF, carries the code and the KSeF number 10.
  • Bookkeeping and third parties. A visualisation can serve as an accounting document if the code allows checking against the source file, and invoices with a KSeF number can be used elsewhere, for example to register a vehicle 9.
  • Agriculture. VAT RR invoices for purchases from flat-rate farmers follow the same marking when used outside KSeF 1.

The duty is not limited to the seller: art. 106gb(5a) and art. 106nda(8) also bind any other entity that uses the invoice outside KSeF 2.

Implementations

No dedicated KSeF QR decoder turned up in this research, and the listed libraries are generators. Because the code is a plain URL, a generic QR reader returns the link.

Project Lang Stars Last active Notes
CIRFMF/ksef-client-csharp C# 115 2026-10 Ministry of Finance library; builds both links, renders and labels the QR 5 23 24
CIRFMF/ksef-client-java Java 49 2026-09 Ministry of Finance library; same functions in Java 5 23 25
smekcio/ksef-client-python Python 29 2026-10 Third-party SDK; verification links, and PNG output through an optional qr extra 26

The normative guide lives in CIRFMF/ksef-api (230 stars), whose offline and certificate chapters sit alongside it 23.

Comparison

  • KSeF QR vs ZBP 2D. A Polish invoice can carry both. ZBP 2D is a payment order for a banking app, while the KSeF code only verifies the invoice and pays nothing 22.
  • KSeF QR vs ZATCA eInvoice QR. A forum copy of the Saudi specification describes Base64-encoded TLV holding the seller, amounts, hash and signature inside the symbol 21. KSeF puts only identifiers, a hash and, on KOD II, a signature into a link, and the invoice details stay in the system, so checking a code means going online.
  • KOD I vs KOD II. KOD I proves a match with a record in KSeF. KOD II covers the period when there is no record yet, by proving who issued the invoice and that it is unchanged 4.

Fun facts

  • In October 2023 the open question was how to link a code to a KSeF number that does not exist yet 19. The published answer leaves the number out of the link altogether, and prints it only as a label 5.
  • The KSeF number moves from the printed label to the bank transfer: from 1 January 2027, art. 108g applies to payments and brings it into transfers 2 8.

Status

Active and mandatory where it applies. The ministry's portal and API documentation were still being updated in October 2026; API version 2.9.0 reached production on 15 October 2026 14.

  • KSeF mandate. From 1 February 2026 for businesses with 2024 sales above PLN 200 million including VAT, and from 1 April 2026 for the others 8. A June 2024 ministry note had planned to count 2025 sales 15. Businesses with invoice sales up to PLN 10,000 gross a month may stay outside KSeF until 31 December 2026 8.
  • Penalties. Art. 106ni allows a fine of up to 100% of the VAT shown, or 18.7% of the gross total where no VAT is shown 3. It covers failing to issue in KSeF, issuing against the template during offline periods, and late submission 2 3. A missing QR code is not listed in the text reviewed.
  • Penalty date. Enacted law says 1 January 2027 2. Sejm print 3245, dated 20 October 2026, would move it to 1 January 2028, with the act taking effect on 31 December 2026 16. The vendor tracker LookupTax listed it on 28 October 2026 as proposed, with its first reading on 21 October 17; the ministry's announcement of 16 September is reported by Firmove 20. The Sejm's own process page could not be read, so check before relying on either date.

Sources

1 Rozporządzenie Ministra Finansów i Gospodarki z dnia 12 grudnia 2025 r. w sprawie korzystania z Krajowego Systemu e-Faktur, Dz. U. 2025 poz. 1815 — Dziennik Ustaw, 2026 2 Ustawa z dnia 5 sierpnia 2025 r. o zmianie ustawy o VAT, Dz. U. 2025 poz. 1203 — Dziennik Ustaw, 2026 3 Ustawa z dnia 16 czerwca 2023 r. o zmianie ustawy o VAT, Dz. U. 2023 poz. 1598 — Dziennik Ustaw, 2026 4 Kody weryfikujące QR — Ministerstwo Finansów, published 30.06.2025, modified 06.02.2026, 2026 5 Kody weryfikujące QR (kody-qr.md) — KSeF 2.0 API documentation, dated 21.08.2025, 2026 6 Kod QR dla faktury wystawionej ONLINE — Ministerstwo Finansów, 2026 7 Kody QR dla faktury wystawionej OFFLINE — Ministerstwo Finansów, 2026 8 Duże firmy — Ministerstwo Finansów, modified 30.10.2025, 2026 9 Pytania i odpowiedzi KSeF 2.0 — Ministerstwo Finansów, modified 08.10.2026, 2026 10 Tryb offline i kody QR — Ministerstwo Finansów, 27.04.2026, 2026 11 Tryby offline (tryby-offline.md) — KSeF 2.0 API documentation, 2026 12 Certyfikaty KSeF (certyfikaty-KSeF.md) — KSeF 2.0 API documentation, 2026 13 Numer KSeF (numer-ksef.md) — KSeF 2.0 API documentation, 2026 14 API changelog — KSeF 2.0 API documentation, 2026 15 Obowiązkowy KSeF odroczony do 1 lutego 2026 r. — Ministerstwo Finansów, 11.06.2024, 2026 16 Druk nr 3245: rządowy projekt ustawy o zmianie ustawy o VAT — Sejm RP, 20.10.2026, 2026 17 Druk 3245: KSeF penalties 2028 — LookupTax (vendor), updated 28.10.2026, 2026 18 Poland: technical specification on QR codes has been published — Sovos (vendor), 19.12.2023, 2026 19 KSeF i kody QR – odpowiedź Ministerstwa Finansów — Akademia LTCA (third party), 13.10.2023, 2026 20 KSeF bez kar do 2028 roku — Firmove.pl (third party), 21.10.2026, 2026 21 Structure of the QR code for electronic tax invoices — Fatoora Developer Community forum, 12.08.2023, 2026 22 Poland country report — Barcoder research corpus, 2026 23 CIRFMF/ksef-api — GitHub, 2026 24 CIRFMF/ksef-client-csharp — GitHub, 2026 25 CIRFMF/ksef-client-java — GitHub, 2026 26 smekcio/ksef-client-python — GitHub, 2026

Deployments

No country reports mention this standard by name.

source · content/standards/poland-ksef-qr/index.md