PlugKit
KSeF Pro WCDocumentationInstallation

KSeF Pro โ€” Installation Guide (WooCommerce)

KSeF Pro for WooCommerce connects your WordPress store to Poland's national e-invoicing system, KSeF (Krajowy System e-Faktur). The plugin generates FA(2) XML invoices, signs them with XAdES-BES digital signatures, and submits them to the Ministry of Finance API โ€” keeping your store compliant with Poland's mandatory e-invoicing requirements without manual intervention.

What is KSeF?

KSeF (Krajowy System e-Faktur) is the Polish government's mandatory electronic invoicing infrastructure. Every B2B VAT invoice issued by a Polish taxpayer must be submitted to KSeF and receive a unique KSeF-ID โ€” a government-assigned identifier that becomes the permanent official record of the transaction for VAT purposes.

Key facts about the mandate:

  • Active for large VAT payers, phased rollout to all Polish VAT payers
  • Applies to B2B domestic transactions; B2C invoices are optional but recommended
  • FA(2) schema version 2.0 mandatory from April 2026
  • KSeF-IDs must be retained for 5 years
  • Non-compliance carries financial penalties per the Polish VAT Act

For a full explanation of the KSeF authentication flow and session lifecycle, see the KSeF Connection page.

Requirements

| Requirement | Minimum | Recommended | |---|---|---| | WordPress | 6.3 | 6.7 | | WooCommerce | 8.0 | 9.4 | | PHP | 8.1 | 8.3 | | PHP extensions | cURL, OpenSSL, SimpleXML | โ€” | | MySQL | 5.7 | 8.0 | | KSeF account | Active token from the MF portal | โ€” | | NIP | Valid Polish tax ID registered in KSeF | โ€” | | WP-Cron | System cron recommended | wp cron event run |

Verify PHP Extensions

php -m | grep -E "curl|openssl|simplexml"

All three must be present. If any is missing, contact your hosting provider โ€” these are standard extensions available on all major PHP-capable hosts.

Memory Requirement

FA(2) XML generation and XAdES-BES signing are memory-intensive for large orders with many line items. Ensure PHP memory limit is at least 128 MB:

php -r "echo ini_get('memory_limit');"

If below 128 MB, increase in wp-config.php:

define('WP_MEMORY_LIMIT', '256M');

HPOS Status

KSeF Pro supports both legacy (wp_postmeta) and HPOS (wc_orders_meta) order storage. The plugin detects the active storage mode automatically โ€” no configuration needed.

HPOS orders list with KSeF-ID column visible after activation

If you plan to migrate to HPOS after installing KSeF Pro, use the built-in WooCommerce migration tool (WooCommerce โ†’ Settings โ†’ Advanced โ†’ Features โ†’ Data synchronisation). KSeF-IDs and audit log entries are preserved during migration.

Step 1: Download the Plugin

After purchasing KSeF Pro on plugkit.io, a download link is emailed within a few minutes. Download ksefpl-woocommerce.zip.

Do not unzip it. WordPress handles extraction automatically.

To re-download, log in to plugkit.io โ†’ My Account โ†’ Orders โ†’ click the download link.

Step 2: Upload via WordPress Admin

  1. Log in to WordPress Admin โ†’ Plugins โ†’ Add New Plugin
  2. Click "Upload Plugin" at the top
  3. Select ksefpl-woocommerce.zip and click "Install Now"
  4. After installation, click "Activate Plugin"

After activation, the plugin appears in your Plugins list as "KSeF Pro โ€” National e-Invoicing for WooCommerce" with status Active.

What Gets Installed

| Component | Details | |---|---| | Plugin files | wp-content/plugins/ksefpl-woocommerce/ | | Database tables | {prefix}_ksefpl_queue (submission queue), {prefix}_ksefpl_audit (audit log), {prefix}_ksefpl_sessions (session tracking) | | WP options | ksefpl_* keys in wp_options (encrypted token, seller data, settings) | | XML storage | wp-content/uploads/ksefpl-xml/ (auto-created with .htaccess protection) | | UPO storage | wp-content/uploads/ksefpl-upo/ (auto-created with .htaccess protection) | | Cron jobs | 4 WP-Cron events registered: ksefpl_process_queue, ksefpl_poll_status, ksefpl_download_upo, ksefpl_retry_failed | | WooCommerce hooks | woocommerce_order_status_changed, HPOS equivalent hooks | | Admin menu | WooCommerce โ†’ KSeF Pro |

Storage Directory Permissions

The XML and UPO upload directories require write permissions for the web server user:

ls -la wp-content/uploads/ | grep ksefpl

Both directories should show the web server user (www-data on Debian/Ubuntu, nginx on CentOS) as owner. If created with wrong ownership:

chown -R www-data:www-data wp-content/uploads/ksefpl-xml
chown -R www-data:www-data wp-content/uploads/ksefpl-upo

The .htaccess files in these directories block direct URL access โ€” do not delete them.

Step 3: Obtain Your KSeF Token

Test Token (Start Here)

  1. Go to https://ksef-test.mf.gov.pl
  2. Log in with Qualified Electronic Signature (QES), Trusted Profile (Profil Zaufany), or seal certificate
  3. Navigate to Tokeny โ†’ Generuj token
  4. Select scopes: Wystawianie faktur (invoice_write) and Dostฤ™p do faktur (invoice_read)
  5. Copy the token โ€” it is shown only once

The test environment is a full-fidelity replica of production. Use it to validate your entire configuration before going live.

Production Token

Follow the same steps at https://ksef.mf.gov.pl. Before generating a production token, verify your NIP is active: navigate to Sprawdลบ status NIP on the portal. New companies or recently re-registered entities may have a delay of 1โ€“2 business days before activation.

Token Scope Warning

A token missing invoice_read scope will submit successfully but silently fail during UPO download. Your audit log will show orders stuck in SUBMITTED status indefinitely. Always generate tokens with both invoice_write and invoice_read.

Step 4: Configure the Plugin

After activation, go to WooCommerce โ†’ KSeF Pro. The settings screen opens on the KSeF Connection tab.

KSeF Pro WooCommerce connection settings

Minimum required settings before testing:

  1. Select Test environment
  2. Paste your test token
  3. Go to Seller Data tab and enter your company NIP and address
  4. Click "Verify connection" โ€” green indicator confirms the NIP/token pair is valid

Proceed to the Configuration guide for full settings documentation.

Step 5: Set Up WordPress Cron

KSeF Pro uses WordPress cron for all background tasks: queue processing, UPO polling, and failed submission retries.

The default HTTP-triggered wp-cron is not reliable for production use. On low-traffic sites it may not run for minutes or hours, causing orders to stay in PENDING status indefinitely.

Recommended: System Cron with WP-CLI

# Step 1: Disable the HTTP wp-cron trigger
# Add to wp-config.php:
define('DISABLE_WP_CRON', true);
 
# Step 2: Add a real cron entry (crontab -e)
*/5 * * * * cd /var/www/yoursite && wp cron event run --due-now --quiet 2>&1 | logger -t wp-cron

This runs all due WordPress cron events every 5 minutes, unconditionally. The logger command sends output to syslog for monitoring.

Alternative: wget/curl Approach

*/5 * * * * wget -q -O /dev/null "https://yourstore.pl/wp-cron.php?doing_wp_cron" 2>&1

Less reliable than WP-CLI because it depends on HTTP response time. Use only if WP-CLI is unavailable.

Verify Cron is Working

After setting up system cron, trigger it manually and check the log:

wp cron event run ksefpl_process_queue
tail -20 wp-content/uploads/ksefpl-logs/ksefpl-$(date +%Y-%m-%d).log

You should see log entries showing queue processing. If the log file is empty after running, enable Debug logging in KSeF Pro โ†’ Advanced โ†’ Logging Level.

Step 6: Verify with a Test Submission

  1. Place a test order in your WooCommerce store (use a test payment gateway)
  2. Move the order to the configured trigger status (default: Processing)
  3. Run the cron manually: wp cron event run ksefpl_process_queue
  4. Check WooCommerce โ†’ KSeF Pro โ†’ Audit Log โ€” the order should appear with status SUBMITTED
  5. Run the poll cron: wp cron event run ksefpl_poll_status && wp cron event run ksefpl_download_upo
  6. Refresh the audit log โ€” status should change to ACCEPTED with a KSeF-ID
  7. Open the order detail โ€” the KSeF Pro meta box should show the KSeF-ID with a download link for the UPO

Updating the Plugin

When a new version is available:

  1. Download the updated ksefpl-woocommerce.zip from plugkit.io
  2. Go to Plugins โ†’ Add New Plugin โ†’ Upload Plugin
  3. Upload the new ZIP and confirm the upgrade prompt

All KSeF-IDs, audit log entries, UPO files, and configuration are preserved across upgrades. If the upgrade includes a database schema change, the migration runs automatically on the first admin page load after update.

After upgrading, clear the WordPress object cache and verify the plugin version in Plugins โ†’ KSeF Pro.

Multisite Installations

KSeF Pro supports WordPress Multisite with per-site activation:

  • Activate the plugin at the network level to make it available to sub-sites, or per-site
  • Each sub-site has its own KSeF token, seller NIP, and configuration
  • Cron events are registered per-site โ€” each site runs its own queue independently
  • If multiple sub-sites share the same legal entity NIP, they share the same KSeF account and KSeF-ID sequence

Post-Installation Checklist

  • [ ] Plugin active in Plugins list
  • [ ] XML and UPO directories exist and are writable
  • [ ] .htaccess blocks present in XML and UPO directories
  • [ ] System cron configured (not HTTP wp-cron)
  • [ ] Token verified โ€” green indicator in KSeF Connection tab
  • [ ] Seller NIP matches the NIP on the KSeF token
  • [ ] Tax class โ†’ VAT code mapping complete
  • [ ] Trigger status configured (default: Processing)
  • [ ] Test order submitted and ACCEPTED in audit log
  • [ ] UPO downloaded and contains valid KSeF-ID
  • [ ] FA(2) XML reviewed โ€” buyer and seller data correct

Next Steps

Edit this page on GitHub
Was this page helpful?

Related Documentation

This topic is also available for other platforms:

KSeF Pro PSKSeF Pro M2

Documentation

InstallationConfigurationKSeF Connection & AuthenticationSending Invoices to KSeFPaired Mode โ€” KSeF Pro + Fakturownia ProTroubleshootingChangelog