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
- Operations audit log
- 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, due date, payment method, 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/
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 the KSeF portal at podatki.gov.pl).
- Set the seller Tax ID and choose the environment (test or production).
- 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 authorization token in the KSeF portal at podatki.gov.pl. A trusted profile (ePUAP) or a qualified electronic signature is required.
-
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 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, audit log 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.
Avis
Il n’y a aucun avis sur cette extension.
Contributeurs & développeurs
« ByteWave Faktury » est un logiciel libre. Les personnes suivantes ont contribué à cette extension.
Contributeurs
Traduisez « ByteWave Faktury » dans votre langue.
Le développement vous intéresse ?
Parcourir le code, consulter le SVN dépôt, ou s’inscrire au journal de développement par RSS.
Historique des changements
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