Configuration
After installing KSeF Pro, open the module configuration from Modules → Module Manager → KSeF Pro → Configure. The configuration screen is organized into four tabs: KSeF Connection, Seller Data, Invoice Settings, and Advanced.
KSeF Connection Tab
Controls how KSeF Pro authenticates with the Ministry of Finance API.
Environment Selection
| Environment | API Base URL | Purpose |
|---|---|---|
| Test | https://ksef-test.mf.gov.pl/api | Development, configuration verification, XML format testing |
| Production | https://ksef.mf.gov.pl/api | Live invoices, real KSeF-IDs, mandatory for compliance |
Always start with Test. The test environment accepts the same FA(2) XML as production and issues real session tokens and UPOs — submissions simply do not appear in your official KSeF ledger.
Switch to Production only after at least one successful test submission with a downloaded UPO.
API Token
Paste the token generated in the KSeF portal. The field accepts tokens from both test and production portals.
After entering your token, click "Verify Token". KSeF Pro sends a lightweight session initiation ping to the selected environment. A green status indicator confirms:
- The token is valid and not expired
- The NIP in Seller Data matches the NIP registered on the token
- The selected environment is reachable from your server
If the verification fails, the error message shown corresponds to the KSeF API error code. The most common causes are NIP mismatch (error 20100) and revoked token (error 10000).
Token scope requirement: The token must have at minimum invoice_write and invoice_read scopes. A token missing invoice_read will submit successfully but fail silently on UPO download — your audit log will show SUBMITTED records that never progress to ACCEPTED.
Seller Data Tab
KSeF requires that the seller identity in every FA(2) XML document exactly match the NIP registered on the token. A mismatch causes the entire session to be rejected with error 20100.
NIP
Enter your 10-digit Polish tax identification number without dashes or spaces (e.g., 1234567890). The PL prefix is stripped automatically.
KSeF Pro validates the NIP checksum on save:
- Weights applied to digits 1–9:
6, 5, 7, 2, 3, 4, 5, 6, 7 - Sum of weighted digits mod 11 must equal digit 10
- Invalid checksum shows a red inline warning — almost always a transcription error
Company Name
Enter the legal name exactly as registered in the Polish business register (KRS or CEIDG). This value populates the <NazwaPodmiotu> element in the <Podmiot1> (seller) block of every FA(2) document.
Address Fields
| Field | FA(2) XML Element | Format | Required |
|---|---|---|---|
| Street and number | <Ulica> | Free text | Yes |
| Postal code | <KodPocztowy> | XX-XXX | Yes |
| City | <Miejscowosc> | Free text | Yes |
| Country code | <KodKraju> | ISO 3166-1 alpha-2 | Yes (default: PL) |
VAT Registration Status
Enable "VAT registered seller" if your company is a czynny podatnik VAT (active VAT payer). This controls:
- Whether the
<StatusVAT>element is included in FA(2) XML - Which tax rate codes are used (
23%,8%,5%,0%,ZW,NP) - Whether OSS annotations are included for EU cross-border sales
If your company is VAT-exempt (zwolnienie z VAT), disable this toggle. The module uses the ZW rate code for all line items and omits the VAT breakdown.
Invoice Settings Tab
Trigger Rule
Determines when KSeF Pro submits invoices. Options:
| Trigger | When it fires | Best for | |---|---|---| | On order status change | When order reaches the selected status | Most stores — standard payment flows | | Manually | Never automatic; use per-order button | Testing, manual review workflows | | On order creation | Immediately after order placement | Stores where payment is guaranteed at placement |
Recommended: "On order status change" with status set to "Payment accepted" (or your equivalent). This ensures invoices are submitted only for paid orders, not abandoned checkouts.
Avoid "On order creation" unless your payment gateway guarantees capture before the order confirmation page is shown. Submitting an FA(2) document to KSeF creates a permanent legal record — it cannot be deleted, only corrected with a FK document.
Tax Rate Mapping
Map each PrestaShop tax rule to the corresponding Polish VAT code used in FA(2) XML.
| Polish VAT Code | Rate | When to use |
|---|---|---|
| 23 | 23% | Standard goods and most services |
| 8 | 8% | Reduced rate goods (selected food, medicine) |
| 5 | 5% | Super-reduced rate (books, basic foods) |
| 0 | 0% | Intra-EU supply, exports outside EU |
| ZW | Exempt | VAT-exempt goods/services (Art. 43 Ustawy o VAT) |
| NP | Not subject | Outside Polish VAT scope entirely |
Open Invoice Settings → Tax Rate Mapping and match each PrestaShop tax rule by name to the correct code. Unmapped rules default to 23% with a warning in the debug log — review the XML preview before going live to catch any misconfigured mappings.
Buyer NIP Collection
Enable "Require NIP for B2B orders" to show a NIP field at checkout. KSeF Pro populates the <Podmiot2> (buyer) block from this field.
For B2C orders without a NIP, the buyer block uses the customer's billing address with identifier type set to BRAK (not applicable). This is valid for B2C transactions under the KSeF schema.
Currency Handling
KSeF requires all monetary amounts in FA(2) XML to be expressed in PLN. For multi-currency stores:
| Priority | Source | Used when | |---|---|---| | 1 | Exchange rate on the order (recorded at purchase) | Order has a stored currency rate | | 2 | NBP daily rate fetched at submission time | Order has no stored rate | | 3 | Manual fallback rate (configurable) | NBP fetch fails |
The applied exchange rate is recorded in the FA(2) <KursWaluty> element for audit purposes. The NBP rate fetch is a live call to api.nbp.pl — ensure this host is also reachable from your server.
Advanced Tab
Retry Policy
KSeF API calls are subject to transient failures (network timeouts, MF server 503 responses during maintenance). Configure:
| Setting | Default | Description |
|---|---|---|
| Maximum retries | 3 | Attempts per failed API call before marking as FAILED |
| Retry interval | 10 seconds | Wait between retry attempts |
| Exponential backoff | Off | Double the interval on each retry (recommended for 503 errors) |
| Close session on each invoice | Off | Close and reopen session after every invoice (reduces throughput but eliminates batch timeout risk) |
For stores submitting fewer than 20 invoices per hour, enabling "Close session on each invoice" is a safe trade-off — it eliminates the 30-minute session timeout risk entirely.
XML Storage
KSeF Pro stores a signed copy of every FA(2) XML document locally before submission. These files are your authoritative audit copy and must be retained for 5 years under Polish tax law.
| Setting | Default | Description |
|---|---|---|
| XML storage path | modules/ksefpl/xml/ | Directory for signed FA(2) XML files |
| UPO storage path | modules/ksefpl/upo/ | Directory for downloaded UPO files |
| Auto-purge | Off | Never purge automatically — legal retention requirement |
Ensure both directories have write permissions for the web server user:
ls -la /path/to/prestashop/modules/ksefpl/Both xml/ and upo/ should show drwxr-xr-x or similar with the web server user as owner.
Logging Level
| Level | Output | When to use | |---|---|---| | Off | No logs | Not recommended | | Error | Failed submissions only | Production (low volume) | | Info | All submissions + KSeF API responses | Production (default) | | Debug | Full HTTP request/response bodies | Troubleshooting only |
Logs are written to var/logs/ksefpl.log. The Debug level writes several kilobytes per API call — disable after debugging to avoid filling disk space on high-volume stores.
Hook Priority
If another PrestaShop module intercepts order status changes (e.g., an ERP connector or another invoicing module), adjust the hook execution order:
| Setting | Default | Notes |
|---|---|---|
| Hook priority | 10 | Higher number = later execution |
Set to 100 if KSeF Pro needs to fire after other modules that modify order data. Set to 1 if KSeF Pro must fire before other modules. The correct value depends on your module stack — test with debug logging to confirm KSeF Pro fires when order data is fully committed.
HPOS Compatibility Mode
PrestaShop 9.x introduced High Performance Order Storage (HPOS) as the default. If you are on PrestaShop 9.x and KSeF Pro is not detecting order status changes:
- Confirm HPOS is enabled: Advanced Parameters → Experimental → Use new storage.
- In KSeF Pro Advanced tab, enable "HPOS compatibility mode".
- Save configuration — this re-registers the order status hooks for the HPOS event system.
Recommended Configuration by Store Type
Standard B2C Polish Store
| Setting | Value | |---|---| | Environment | Production | | Trigger | On order status change: Payment accepted | | Buyer NIP | Optional (shown at checkout, not required) | | Tax mapping | All rules → 23% (adjust for reduced-rate goods) | | Session mode | Batch (default) | | Retry | 3 attempts, 10s interval |
B2B Software Licence Store
| Setting | Value | |---|---| | Environment | Production | | Trigger | On order status change: Payment accepted | | Buyer NIP | Required for B2B customer group | | Tax mapping | Standard goods → 23%, software licences → 23% (GTU_12) | | Paired mode | Enabled (pair with Fakturownia Pro) | | Session mode | Close after each invoice |
Mixed B2B/B2C Store
| Setting | Value | |---|---| | Buyer NIP | Optional — shown at checkout, required when Company field filled | | VIES validation | On — applies 0% VAT for verified EU B2B buyers (Reverse Charge) | | Tax mapping | Standard 23% + ZW for exported software |