Description
ByteWave Faktury is a plugin that integrates your WooCommerce store with the Polish National e-Invoice System (KSeF), operated by the Polish Ministry of Finance.
The plugin allows you to generate structured XML e-invoices (FA(3) schema), validate them and send them to KSeF – directly from the WooCommerce admin panel.
Features in the free version
- Manual issuance of KSeF invoices from a WooCommerce order screen
- XML generation compliant with the FA(3) schema
- XSD validation of documents before sending
- Sending invoices to KSeF (test and production environments)
- Processing result from KSeF: KSeF number for accepted invoices, rejection reason for rejected ones
- Downloading UPO (Official Receipt Confirmation)
- KSeF token encryption (XChaCha20-Poly1305) and session encryption (AES-256-CBC + RSA)
- Settings panel with connection test
- Private storage of XML and UPO files in a randomly named, access-protected directory
- Compatibility with HPOS (High-Performance Order Storage) and classic CPT
- Full Polish language support
Companion Pro plugin
ByteWave Faktury Pro is a separate companion plugin (not hosted on WordPress.org)
that adds advanced automation features when installed alongside the Free version:
- Automatic invoice issuance after order payment
- Bulk invoice issuance and sending (bulk actions)
- Reports dashboard with statistics and KPIs
- Order data checks before sending to KSeF
- KSeF availability monitoring with email alerts
The Pro plugin is distributed from the author’s website and is not required for
the Free version to work. More information: https://ksef-woocommerce.pl/
Requirements
- WordPress 6.0 or newer
- WooCommerce 8.0 or newer
- PHP 7.4 or newer
- PHP Sodium extension (libsodium) – required for token encryption
- Active KSeF account with a generated authorization token
External services (Third-Party Services)
This plugin connects to the following external services. Full disclosure below.
Service: Polish National e-Invoice System (KSeF), operated by the Polish Ministry of Finance.
What the service is and what it is used for:
KSeF is the official electronic invoicing system of the Republic of Poland (Krajowy System e-Faktur). This plugin uses the KSeF API to submit structured XML invoices generated from WooCommerce orders, retrieve their status, and download the official receipt confirmation (UPO, Urzędowe Poświadczenie Odbioru). Communication with the KSeF API is the core functionality of this plugin and the integration cannot be performed locally.
What data is sent, and under what circumstances:
Data is transmitted to the KSeF API only after explicit user action: clicking the “Wystaw fakturę” (Issue invoice) button on an order, or when the WordPress cron worker processes a previously-queued invoice that the user has manually created. The following fields are sent: seller business data (Tax ID / NIP, company name, address), buyer business data (NIP or personal identifier, name, address), invoice line items (product names, quantities, unit prices, VAT rates, totals), invoice metadata (issue date, currency, invoice number). The encrypted KSeF API authorization token (configured by the site owner in plugin settings) is sent in each request to authenticate the connection. No usage analytics, telemetry, or personally identifiable data unrelated to the invoice is transmitted.
API endpoints used:
* Production: https://api.ksef.mf.gov.pl/v2
* Test (sandbox): https://api-test.ksef.mf.gov.pl/v2
Service information and legal documents:
* KSeF service homepage and terms of service: https://www.podatki.gov.pl/ksef/
* Privacy policy of the Polish Ministry of Finance: https://www.gov.pl/web/finanse/polityka-prywatnosci
* KSeF API documentation (developer zone): https://www.podatki.gov.pl/ksef/strefa-deweloperow/
Service: National Bank of Poland (NBP) Web API – exchange rates.
What the service is and what it is used for:
Polish VAT law requires the VAT amount on an invoice issued in a foreign currency (for example EUR) to be stated in Polish zloty, converted with the average NBP exchange rate from the last business day before the tax point. The plugin downloads this public exchange rate from the NBP Web API.
What data is sent, and under what circumstances:
Only when an invoice is generated for an order placed in a currency other than PLN. The request contains only the currency code and a date range (for example EUR and the ten days before the sale date). No personal, order or store data is sent. Downloaded rates are cached for a week. Developers can supply the rate from another source with the bwksef_exchange_rate filter.
API endpoint used:
* https://api.nbp.pl/api/exchangerates/rates/a/
Service information and legal documents:
* NBP Web API documentation: https://api.nbp.pl/en.html
* NBP privacy policy: https://nbp.pl/en/privacy-policy/
Service: KSeF status service (Latarnia), operated by the Polish Ministry of Finance.
What the service is and what it is used for:
Latarnia publishes the official status of KSeF, including announced maintenance and failures. The legal deadline for sending an invoice held during an outage depends on that status, so the plugin reads it when it holds an invoice for the production environment.
What data is sent, and under what circumstances:
A plain request without any shop, customer or invoice data. It happens only for the production environment: when KSeF does not answer while an invoice is being sent, and when an administrator opens the connection tools screen. The answer is remembered for one minute.
API endpoint used:
* https://api-latarnia.ksef.mf.gov.pl/status
Service information and legal documents:
* KSeF service homepage and terms of service: https://www.podatki.gov.pl/ksef/
* Privacy policy of the Polish Ministry of Finance: https://www.gov.pl/web/finanse/polityka-prywatnosci
Link to the invoice in the Ministry of Finance system.
The email to the customer and the order details on the My Account page contain a link to https://qr.ksef.mf.gov.pl/invoice/ with the seller’s tax number, the invoice date and the invoice hash. The plugin does not call this address. The Ministry of Finance receives these values only when the customer opens the link. The email can be switched off under WooCommerce > Settings > Emails.
This plugin does not communicate with any other external servers. It does not collect analytics or telemetry, does not phone home, does not load remote assets, and does not contact any author-owned backend.
Installation
- Download the plugin ZIP file.
- In the WordPress admin go to: Plugins > Add New > Upload Plugin.
- Select the downloaded ZIP file and click “Install Now”.
- Activate the plugin.
- Go to KSeF > Settings.
- Paste the KSeF authorization token, generated in Aplikacja Podatnika KSeF (ap.ksef.mf.gov.pl for production, ap-test.ksef.mf.gov.pl for the test environment).
- Enter the seller Tax ID and the full company name, and choose the environment (test or production). The company name is required: without it the plugin does not issue invoices.
- Set the mode to “Wysyłka do KSeF”. In the default simulation mode invoices get the “Symulacja” status and nothing reaches KSeF.
- Click “Test connection” to verify the configuration.
- Done – you can now issue KSeF invoices from WooCommerce orders.
System requirements
- PHP 7.4+ with the Sodium extension (check in phpinfo())
- WooCommerce 8.0+
- SSL certificate (HTTPS) – required by the KSeF API
- KSeF authorization token
FAQ
Does the plugin require WooCommerce?
Yes, the plugin requires WooCommerce installed and active in version 8.0 or newer.
How do I obtain a KSeF token?
You generate the token in Aplikacja Podatnika KSeF: ap.ksef.mf.gov.pl for production and ap-test.ksef.mf.gov.pl for the test environment. Log in with a trusted profile (Profil Zaufany), a qualified electronic signature or a qualified seal. Create a separate token for this plugin with only the permission to issue invoices (InvoiceWrite). Tokens from KSeF 1.0 do not work in KSeF 2.0.
Is my data safe?
The KSeF token is encrypted with the XChaCha20-Poly1305 algorithm (libsodium) and stored in the database in encrypted form. Communication sessions with KSeF are encrypted using AES-256-CBC + RSA. XML and UPO files are stored in a randomly named directory inside wp-content/uploads, protected with index.php files and an .htaccess rule (Apache, LiteSpeed). On Nginx, add a rule denying access to /wp-content/uploads/bytewave-ksef-private/ in the server configuration.
Does the plugin work with the KSeF test environment?
Yes. In the settings you can choose the environment: test (sandbox) or production. We recommend starting with the test environment.
Does the plugin work with HPOS (High-Performance Order Storage)?
Yes, the plugin is fully compatible with both HPOS and the classic order storage mode (CPT).
Where does the plugin read the buyer’s Tax ID (NIP) from?
From the NIP field added by this plugin, which works in the block and classic checkout, on the My Account page and on the order screen. If your shop already collects the number with another plugin, the field stays switched off and the plugin reads the order fields used by popular checkout and invoicing plugins (for example _billing_nip, billing_nip, _billing_vat_number, _vat_number, _billing_eu_vat_number). A Polish NIP must have a valid checksum; an EU VAT number (for example DE123456789) is sent as an EU VAT number. Developers can add their own field with the bwksef_buyer_tax_id_meta_keys filter.
I sell with the “zw” (VAT exempt) rate. What do I need to set?
Go to KSeF > Settings > Invoice and enter the legal basis of the exemption (for example “art. 113 ust. 1 ustawy o VAT”). Invoices with exempt items are not issued without it, because the legal basis is a mandatory part of such an invoice.
How does the free version differ from Pro?
This Free plugin provides manual invoice issuance directly from each WooCommerce order screen, automatic queue processing for reliable delivery, and offline storage when the KSeF API is temporarily unavailable. The optional companion Pro plugin (distributed separately at ksef-woocommerce.pl) adds advanced automation features such as auto-issue on order payment, bulk operations, reports dashboard, order data checks and email alerts.
Where can I get help?
Use the support forum on WordPress.org or contact us via the form at ksef-woocommerce.pl.
Changelog
1.4.0
- New: NIP field for customers in the block and classic checkout, on the My Account page and on the order screen, with validation of the Polish NIP and EU VAT numbers. It stays off when the shop already collects the number, and it has a switch on the Invoice settings tab
- New: Start screen with seven steps from installation to production KSeF, showing the live state of each step, and a settings check
- New: email to the customer once KSeF accepts the invoice, with the invoice number, the KSeF number, the amount and a link to the document in the Ministry of Finance system. The link is also shown on the My Account page
- New: an invoice that could not be created now appears on the list with an error and an email, instead of only an order note. When the exchange rate service is down, it is retried automatically
- New: invalid NIP stops the invoice with an email, instead of treating the company as a consumer
- New: split payment mark. A product can be marked as listed in annex 15, and an invoice above 15 000 PLN for a company with a Polish NIP gets the mark automatically
- New: invoice for a receipt (FP mark), set on the order screen
- New: option for sellers exempt from VAT
- New: token expiry date with reminders 30 and 7 days before it, by email and in the panel
- New: notice in December 2026 about the end of the 10 000 PLN exception
- New: warning on all admin screens when the invoice queue has stopped because WordPress is not running background tasks
- New: pausing sending to KSeF now shows a permanent banner, the official KSeF status is shown for the production environment, and the invoice shows the mode reported by KSeF
- Fix: one invoice number for an order. A retry on another day no longer creates a new number, which could lead to a second invoice in KSeF
- Fix: refunds made before the invoice is issued are subtracted from the invoice. A refund of an amount without order lines stops the invoice, because the plugin cannot tell what it applies to
- Fix: the deadline for an invoice held during a KSeF outage is counted from the invoice date and the official KSeF status, and it no longer moves on each attempt. An email warns about a deadline that is coming up. Invoices with an older date are sent with the offline mark
- Fix: an invoice waiting in the queue gets the current date before sending, with the same number, if nobody has received the document and the legal deadline has not passed. Dates are counted in the Polish time zone
- Fix: when KSeF asks to wait (Retry-After), the queue waits for the full time instead of retrying after 10 seconds
- Fix: a retry after an unclear answer from KSeF sends exactly the same file, because KSeF recognises a duplicate only by the same content. Such an invoice cannot be cancelled, because a new one would get another number. After checking in KSeF you can confirm on the order screen that the invoice is not there
- Fix: a refund already subtracted on the invoice no longer raises the correction alarm
- Fix: a manual retry follows the same rules for the invoice date as sending from the queue
- Fix: the sentence about the bank transfer title is shown only for a buyer with a Polish NIP and a seller who is not exempt from VAT
- Fix: the Help screen no longer points to screens that exist only in Pro, and the Contact tab has an address
- Tweak: requires WooCommerce 8.9 or newer
1.3.0
- New: protection against sending from a site copy. Production KSeF works only at the address where it was enabled and is refused when WordPress is marked as staging, development or local. Invoices wait in the queue, and a red notice explains what to do
- New: an alarm when an order with an invoice already in KSeF is refunded, cancelled or deleted: an order note, a “Requires correction” mark and an email with the invoice data
- New: invoices from simulation mode have their own “Simulation” status instead of “Sent”, with a permanent banner. After switching the mode a real invoice can be issued from the order screen. Automation does not replace them on its own. Existing simulated invoices are moved to the new status
- New: “Cancel” for invoices that did not reach KSeF
- Fix: a service for an EU company now gets the np II code with the reverse charge mark, and the seller gets the PL prefix on 0 WDT and np II invoices
- Fix: shipping and fees next to goods at 0% now follow the goods code (0 WDT, 0 EX) instead of np I, which also switched on reverse charge for the whole invoice
- Fix: an invoice is stopped with a clear message when the order already has a refund, when its total differs from the sum of the lines, or when the seller name is empty (previously the site name was used)
- Fix: an invoice waiting in the queue is no longer sent after the order was cancelled or refunded
- Fix: a queued invoice from another environment no longer holds up the rest of the queue
- Fix: a test KSeF number is no longer shown to customers or saved in the order
- Fix: manual offline mode can be switched off, and waiting invoices can be sent when KSeF is available
- Fix: a company outside Poland without a tax number is no longer stopped with a message about a missing NIP
- Fix: settings and actions show their result again: saving, a wrong Tax ID, a missing UPO or XML file, processing the queue
- Fix: the queue survives a missing WooCommerce, an exception from another plugin and an invoice left without a job, and “Retry” no longer replaces the XML while it is being sent
- Tweak: a clear message when WooCommerce taxes are switched off
1.2.0
- New: customers see the KSeF number of their invoice in WooCommerce emails and in the order details on the My Account page once KSeF has accepted the invoice. From 1 January 2027 Polish active VAT payers enter this number in the title of bank transfers
- New: “KSeF number for the customer” option on the Invoice settings tab (enabled by default) and the bwksef_show_ksef_number_to_customer filter
- Tweak: clearer wording of several admin texts
1.1.0
- New: the plugin reads the processing result from KSeF. Accepted invoices get their KSeF number (also saved in the order as _bwksef_ksef_number with an order note); rejected invoices get the “Rejected” status with the reason returned by KSeF
- New: handling of KSeF error 21184 (session temporarily unavailable), automatic resend when KSeF cancels processing (codes 405 and 550) and duplicate detection (code 440)
- New: settings tab “Invoice” with an optional invoice number prefix and the legal basis for VAT-exempt (“zw”) items
- New: “Test connection” in settings now performs a real authentication in KSeF
- New: foreign currency invoices contain the VAT amount in PLN calculated with the NBP average exchange rate
- Fix: saving one settings tab no longer switches off options on other tabs (admin notifications, NIP validation)
- Fix: permissions of the KSeF Accountant role are no longer reset when settings are saved by a companion extension
- Fix: the KSeF box is now shown on the order edit screen when HPOS is enabled, with the KSeF number and XML/UPO download buttons
- Fix: clicking “Issue invoice” twice (or parallel requests) no longer creates duplicate invoices; invoices are not issued for cancelled, refunded or failed orders
- Fix: an invalid token, missing settings or XML validation errors are no longer treated as KSeF unavailability, so invoices no longer get stuck in the offline status; invoices waiting for KSeF are sent automatically when it is available again
- Fix: FA(3) XML: postal code and city in addresses, correct order of VAT summary fields (e.g. 23% with 8% and reverse charge), “np I”/”np II” codes, fees (e.g. cash on delivery) as invoice lines, unit of measure, EU VAT numbers of EU business buyers, removal of characters not allowed by KSeF
- Fix: the buyer’s NIP is read only from Tax ID fields and must have a valid checksum (other 10-digit order data is no longer treated as a NIP)
- Fix: the invoice issue date is the actual issue date instead of the order date
- Fix: retry intervals of the sending queue (timezone mismatch) and release of stale locks
- Fix: token problems trigger one notification instead of one email per invoice
- Fix: offline deadlines no longer require the PHP calendar extension; December 24 is treated as a public holiday
- Security: stronger protection of the private XML/UPO directory, stricter sanitization of settings, masking of tokens in diagnostics
- Tested with WordPress 7.1 and WooCommerce 11.1
1.0.1
- Fix: saving settings from a companion extension no longer re-encrypts the stored KSeF token (prevents the token from becoming unreadable)
- Fix: settings added by companion extensions are preserved on save instead of being dropped
1.0.0
- First public release
- Integration with the KSeF API (test and production environments)
- FA(3) XML generation with XSD validation
- Manual invoice issuance from a WooCommerce order
- Invoice status preview and UPO download
- Token encryption (XChaCha20-Poly1305) and session encryption (AES-256-CBC + RSA)
- Private storage of XML/UPO files
- Settings panel with a connection test
- Compatibility with HPOS and classic CPT
- Full Polish localization
