KSeF E-Invoicing for OpenCart — FA(3) e-invoices to Poland’s KSeF straight from orders

KSeF E-Invoicing for OpenCart is a module for shops in Poland that invoice businesses. From 2026 Polish VAT payers send B2B invoices through the National e-Invoice System (Krajowy System e-Faktur, KSeF). The module turns an OpenCart order into a structured invoice in the official FA(3) format and sends it straight to the KSeF API 2.0 — no accounting SaaS in between and no monthly subscription. The KSeF number, the official receipt (UPO) and the verification QR code are stored on the order. Builds for OpenCart 4.x, 3.x and 2.3.

What you need. A KSeF token for your company’s NIP, generated in the KSeF taxpayer application (Aplikacja Podatnika KSeF) of the chosen environment (“Tokeny” section, invoice write and read permissions). Honestly about testing: the module has been tested on the official KSeF TEST environment of the Ministry of Finance on OpenCart 4.1, 4.0.2, 3.0.5 and 2.3 — invoices were accepted with real KSeF numbers and UPO, and every XML is valid against the official FA(3) XSD. We have not run it on DEMO or PRODUCTION yet: same API there, but it needs a real company. Try it on your own NIP with the 7-day Pro trial — if KSeF answers differently than on TEST, we fix it promptly.

The shop remains responsible for the invoice content: the module builds FA(3) from the OpenCart order data (products, order total lines, taxes, addresses, NIP). Tax decisions — how a coupon is spread over rates, when 0% WDT or EX applies, when an order counts as paid, the correction type — follow OpenCart’s logic and the Ministry of Finance documentation; show the settings to your accountant before switching to PRODUCTION.

What the customer sees

The module adds a native OpenCart custom field “NIP (for a VAT invoice)” — the “Create the NIP field” button in the settings creates it. The default checkout, registration, account pages and One Page Checkout (CatCode) show it. It is optional: without a NIP the order goes through as usual and no KSeF invoice is created. When a NIP is entered, the module checks its checksum — a wrong number stops the checkout with an error next to the field. “5265877635”, “526-587-76-35” and “PL5265877635” are all accepted, as are VAT numbers of other EU countries (invoicing such buyers needs Pro).

On a phone it works the same way: the error shows under the field, the rest of the checkout is unchanged. A customer who already has an account in OpenCart 4 sees the NIP field in their account, not at checkout — that is how OpenCart shows account fields. For such orders you can enter the NIP on the order page in the admin (see below).

With Pro the customer gets the e-mail “Your invoice is in KSeF” with the KSeF number and QR code, an invoice block on the order page of their account and a printable invoice behind a keyed link. The printable invoice is an information copy; the legally binding invoice is the XML in KSeF.

What the admin gets

• Extensions → Modules → KSeF E-Invoicing: tabs “Invoices”, “Settings”, “Tools” and “Licence”.
• The KSeF token is stored encrypted, with the encryption key in the file storage/cc_ksef.key.php, not in the database; the form only shows “saved”. You can also set the token with the CC_KSEF_API_TOKEN constant in config.php.
• “Check the connection to KSeF” runs a full authentication and tells you which NIP and environment work, or shows the KSeF error in words (e.g. 450 for a wrong token).
• Environment — TEST, DEMO or PRODUCTION; while TEST or DEMO is on, a notice at the top reminds you that invoices have no legal effect.
• Statuses that issue the invoice, the seller (Podmiot1) with KRS / REGON / BDO, number format, VAT source, unit of measure, shipping line prefix, order total lines that are payments (gift vouchers, store credit), payment term and IBAN for bank transfer orders.

• Invoice register: number, order, buyer with NIP, total, status, KSeF number or rejection text; status filter, search and pagination.
• “Send queued invoices now” sends the queue at once, including invoices waiting for a retry.
• Order history notes: “created and queued”, “accepted, KSeF number …” or the rejection reason.

The KSeF panel on the order page: the buyer’s NIP with its validation mark, a field to enter or correct the NIP just for the invoice (the customer’s own field is not changed), status, KSeF number, KOD I QR code and a link to the details. An order without an invoice gets an “Issue KSeF invoice” button, and when there is no invoice for a reason (e.g. a consumer order), the panel says why.

The invoice page: date, status, KSeF number, session, SHA-256 of the file, “Download XML”, “Download UPO”, the printable invoice, the QR code and the full FA(3) XML that KSeF saw. A rejected invoice shows the KSeF text in Polish and the “Regenerate and send” (after fixing the data) and “Discard” buttons. With Pro the same page has the correction invoice form: returned quantities per line and / or a price reduction spread over the VAT rates; the module will not correct more than is left.

Number already used by another program. If you also issue invoices on the same NIP in another program or another shop with the same number pattern, KSeF refuses the second invoice with that number (code 440). The module compares the file with the UPO of the original: its own file (e.g. when the KSeF response was lost) is taken over with its KSeF number, a foreign one never. Such an invoice becomes “Rejected by KSeF” with an explanation and the other document’s KSeF number; change the number format (e.g. a SKLEP/ prefix) and click “Regenerate and send” — the invoice gets a new number. While the original cannot be compared yet, the invoice stays in processing for up to 24 hours and is checked every 2 minutes.

How it works — step by step

1. Setup. KSeF token → “Check the connection to KSeF” → seller data → “Create the NIP field” → switch on “Issue KSeF invoices”. Start on the TEST environment.
2. Checkout. A business buyer enters the NIP. A wrong NIP will not pass; without a NIP it is a regular order without an invoice.
3. Order status. The order gets a chosen status (default: the shop’s “complete” statuses) — the module builds an FA(3) invoice with the next number and queues it. Lines come from the order products and order total lines: shipping, fees, coupons (spread over the rates).
4. Sending. On a PHP-FPM server the invoice goes out right after the admin page responds; on top of that the queue is checked by the OpenCart 4 scheduler (hourly), by the keyed cron address from the “Tools” tab (every 5 minutes recommended) and when the admin is opened.
5. KSeF status. Accepted — the KSeF number and QR code on the order; the UPO appears in KSeF shortly after the number and is fetched on the next pass. Rejected — the reason in the register, on the invoice page and in the order history.
6. Failures. KSeF down, 429 or 503 — the invoice waits and retries by itself; the same XML byte for byte, so there is never a second invoice.
7. Returns (Pro). The order gets a correction status (Refunded / Reversed by default) — a full KOR correction invoice with the original’s KSeF number; partial corrections by hand on the invoice page.
8. Customer (Pro). The e-mail “Your invoice is in KSeF” with the KSeF number and KOD I QR code, a block in the account and a printable invoice.

Under the hood

• FA(3), schema 1-0E — element order strictly per the Ministry of Finance XSD; every invoice from the test runs on OpenCart 4, 3 and 2.3 (B2B with several rates, coupons, EUR, EU, B2C, KOR) is valid against the official schema.
• KSeF API 2.0 without third-party libraries: token authentication (RSA-OAEP SHA-256), online session, AES-256-CBC, status polling, UPO. Access and refresh tokens are cached; a 401 triggers re-authentication.
• Totals as in the order. Coupons and discounts are spread over the rates in proportion to the products’ net amounts, shipping and fee tax comes from the order’s tax lines, and the rounding remainder goes into the largest line — the invoice P_15 equals the order total, in PLN and in a second currency.
• Payment: cash on delivery → form 1, bank transfer → form 6 with the IBAN from the settings; “paid” by the chosen statuses, otherwise a payment term.
• The XML never changes after it is created. A retry sends the same file, so a lost KSeF response gives a 440 with the original number, not a second invoice. A 440 duplicate is taken over only for the module’s own file (SkrotDokumentu from the original’s UPO or the SHA-256 of the file from KSeF).
• Numbering with a lock (MySQL GET_LOCK): two orders in the same second never get the same number.
• NBP rate (Pro) — table A of the last business day before the date of sale; the XML has KursWaluty and VAT in PLN (P_14_xW). A printable invoice in EUR shows the rate, VAT in PLN is in the XML.
• Own tables (cc_ksef_invoice, cc_ksef_order, cc_ksef_kv) and OpenCart events — no core file edits: install.xml in the 3.x and 2.3 builds contains no modification.
• KSeF offline modes (offline24, emergency, KOD II) are not implemented: while KSeF is down, invoices wait in the queue.
• Uninstalling. OpenCart itself erases the module settings, so after a reinstall the token and seller data are entered again; the invoice register, counters and licence stay. The “Delete data on uninstall” switch removes the register too.

Installation

1. OpenCart 4: Extensions → Installer → upload cc_ksef.ocmod.zip (do not rename the archive) and click “Install”. OpenCart 3: Extensions → Installer → cc_ksef-oc3.ocmod.zip. OpenCart 2.3: copy the contents of the upload/ folder from cc_ksef-oc2.ocmod.zip to the shop root (FTP or the hosting file manager) — the 2.3 installer needs FTP access, uploading by hand is simpler.
2. Extensions → Extensions → Modules → KSeF E-Invoicing → “Install”, then “Edit”.
3. TEST environment, a token from the KSeF taxpayer application of the same environment, “Check the connection to KSeF”.
4. Seller data, number format (your own prefix if another invoicing program is in use) and VAT source; “Create the NIP field”; switch on “Issue KSeF invoices”.
5. Place a test order with a NIP and set it to “Complete” — within a minute the order page shows the KSeF number.
6. Moving to PRODUCTION — switch the environment and paste the PRODUCTION token.
7. For Pro: the “Licence” tab — the key from the e-mail after payment, or the 7-day trial.