KSeF Pro — Installation Guide (Magento 2)

KSeF Pro for Magento 2 connects your store to Poland's national e-invoicing system, KSeF (Krajowy System e-Faktur). The extension generates FA(2) XML invoices, signs them with XAdES-BES digital signatures, and submits them to the Ministry of Finance API using Magento's native cron infrastructure and observer pattern.

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 VAT record for that transaction.

Key facts:

FA(2) schema version 2.0 is mandatory from April 2026
KSeF-IDs must be retained for 5 years (ustawa o rachunkowości)
Non-compliance carries financial penalties under the Polish VAT Act
The KSeF-ID replaces the invoice number as the primary VAT reference in audits

For a full explanation of the KSeF authentication flow and FA(2) XML format, see the KSeF Connection page.

Requirements

| Requirement | Minimum | Recommended | |---|---|---| | Magento Open Source | 2.4.5 | 2.4.7-p3 | | Adobe Commerce | 2.4.5 | 2.4.7-p3 | | PHP | 8.1 | 8.3 | | PHP extensions | cURL, OpenSSL, SimpleXML, Intl | — | | Composer | 2.x | 2.7+ | | KSeF account | Active token from the MF portal | — | | NIP | Valid Polish tax ID registered in KSeF | — |

PHP Extension Check

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

All four must be present. Intl is used for locale-aware date formatting in FA(2) XML. If missing:

# Debian/Ubuntu
apt-get install php8.3-intl
service php8.3-fpm restart

Magento Mode

KSeF Pro works in both developer and production mode. In production mode, setup:di:compile is required after installation (generates optimized interceptor classes). In developer mode it is optional but recommended.

Step 1: Add the Composer Repository

KSeF Pro is distributed via a private Composer repository at packages.plugkit.io. After purchasing on plugkit.io, your license credentials are emailed with your order confirmation.

# Add the repository
composer config repositories.plugkit composer https://packages.plugkit.io
 
# Add your credentials
composer config http-basic.packages.plugkit.io YOUR_LICENSE_KEY YOUR_ORDER_ID

Your license key and order ID are in your plugkit.io order confirmation email and in My Account → Orders on plugkit.io.

CI/CD Environments

For CI/CD pipelines where interactive credential entry is not possible, use environment variables:

export COMPOSER_AUTH='{"http-basic":{"packages.plugkit.io":{"username":"LICENSE_KEY","password":"ORDER_ID"}}}'

Or add to the CI/CD service's secret store and reference in the pipeline script.

Adobe Commerce Cloud

For cloud environments, add credentials to the cloud environment:

magento-cloud variable:set env:COMPOSER_AUTH \
  '{"http-basic":{"packages.plugkit.io":{"username":"LICENSE_KEY","password":"ORDER_ID"}}}' \
  --sensitive=true

Step 2: Install via Composer

composer require plugkit/module-ksefpl

Verify the package installed successfully:

composer show plugkit/module-ksefpl
# Expected output: name, version, description

What Gets Installed

| Component | Details | |---|---| | Module files | app/code/PlugKit/KsefPl/ | | Database tables | ksefpl_queue (submission queue), ksefpl_audit (audit log), ksefpl_sessions (session tracking), ksefpl_invoice_registry (KSeF-ID to Magento invoice mapping) | | Configuration | PlugKit_KsefPl section in core_config_data | | XML storage | var/ksefpl/xml/ (created during setup:upgrade) | | UPO storage | var/ksefpl/upo/ (created during setup:upgrade) | | Cron jobs | 4 jobs in crontab.xml under default group | | Observers | sales_order_invoice_save_after, credit memo events | | CLI commands | ksefpl:test-connection, ksefpl:queue-status, ksefpl:process-queue, ksefpl:check-tax-mapping, ksefpl:retry-failed | | Admin menu | Sales → KSeF Pro |

Step 3: Enable the Module

Run the standard Magento module installation sequence:

# Enable the module
php bin/magento module:enable PlugKit_KsefPl
 
# Run setup scripts (creates database tables and default config)
php bin/magento setup:upgrade
 
# Compile dependency injection (required for production mode)
php bin/magento setup:di:compile
 
# Flush all cache types
php bin/magento cache:flush

For production mode deployments, also deploy static content:

php bin/magento setup:static-content:deploy pl_PL en_US

DI Compilation Notes

setup:di:compile generates interceptor classes for all registered plugins and preferences. KSeF Pro registers:

InvoiceSaveAfterObserver — hooks into invoice save events
KsefConnectionService — manages authentication sessions
FA2XmlBuilder — generates FA(2) XML from invoice data

If compilation fails, see Troubleshooting → DI Compilation Errors.

Step 4: Verify Installation

php bin/magento module:status PlugKit_KsefPl
# Expected: Module is enabled

After enabling, the module appears at Stores → Configuration → PlugKit → KSeF Pro in the Magento Admin.

Verify database tables were created:

mysql -u magento -p magento -e "SHOW TABLES LIKE 'ksefpl_%';"
# Expected: 4 rows (ksefpl_queue, ksefpl_audit, ksefpl_sessions, ksefpl_invoice_registry)

Step 5: Obtain Your KSeF Token

Test Token (Start Here)

Go to https://ksef-test.mf.gov.pl
Log in with QES, Trusted Profile (Profil Zaufany), or seal certificate
Navigate to Tokeny → Generuj token
Select scopes: Wystawianie faktur (invoice_write) and Dostęp do faktur (invoice_read)
Copy the token — shown only once

Production Token

Follow the same steps at https://ksef.mf.gov.pl. Before generating a production token, verify NIP status: Sprawdź status NIP. New companies may have a delay before activation.

Required Scopes

| Scope | Polish label | Required for | |---|---|---| | invoice_write | Wystawianie faktur | Submitting FA(2) XML | | invoice_read | Dostęp do faktur | Downloading UPOs |

A token missing invoice_read submits successfully but fails silently during UPO download — audit log shows SUBMITTED records that never reach ACCEPTED.

Step 6: Configure the Extension

Open Stores → Configuration → PlugKit → KSeF Pro. Set:

Environment: Test
Paste your test token in the KSeF API Token field
Click "Test KSeF Connection" — green indicator required before proceeding
Enter your seller NIP, company name, and address in the Seller Data section
Map Magento tax rules to Polish VAT codes in Tax Rate Mapping

Proceed to the Configuration guide for full settings documentation.

KSeF Pro connection configuration in Magento System Configuration

Adobe Commerce Cloud Installation

For Adobe Commerce on Cloud, add the extension via Composer and push to the cloud Git repository:

# Local
composer require plugkit/module-ksefpl
 
# Commit updated lock files
git add composer.json composer.lock
git commit -m "feat: add KSeF Pro for Magento 2"
git push origin <branch>

The cloud build pipeline runs setup:upgrade and setup:di:compile automatically. Monitor the build:

magento-cloud activity:log --tail

Verify the module is enabled in the deployed environment:

magento-cloud ssh -- php bin/magento module:status PlugKit_KsefPl

Cloud Variable for KSeF Token

On cloud environments, it is safer to store the KSeF token as a cloud environment variable rather than entering it through the Admin UI (which stores it in the database):

magento-cloud variable:set --name=KSEFPL_API_TOKEN --value="your-token-here" --sensitive=true

KSeF Pro checks for this environment variable before reading from core_config_data, giving it highest priority.

Updating the Extension

composer update plugkit/module-ksefpl --with-dependencies
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

All KSeF-IDs, audit log entries, UPO files, and configuration are preserved across upgrades. Database schema migrations run automatically via setup:upgrade.

After updating, verify the module version:

composer show plugkit/module-ksefpl | grep versions

And test the KSeF connection to confirm credentials are still valid.

Uninstalling

php bin/magento module:disable PlugKit_KsefPl
php bin/magento setup:upgrade
composer remove plugkit/module-ksefpl
php bin/magento cache:flush

To permanently remove KSeF Pro's database tables — export the audit log CSV first:

php bin/magento ksefpl:export-audit --output=/tmp/ksefpl-audit-export.csv
php bin/magento setup:uninstall PlugKit_KsefPl

setup:uninstall permanently deletes all submission records. KSeF-IDs and UPO files in var/ksefpl/ must be archived separately before uninstalling to satisfy the 5-year retention requirement.

Post-Installation Checklist

[ ] module:status PlugKit_KsefPl shows "Module is enabled"
[ ] 4 ksefpl_* database tables present
[ ] var/ksefpl/xml/ and var/ksefpl/upo/ directories exist and are writable
[ ] Token verified — green indicator in Stores → Configuration → KSeF Connection
[ ] Seller NIP matches the NIP on the KSeF token
[ ] Tax rate mapping complete (all active Magento tax rules mapped)
[ ] System cron running (*/2 * * * * minimum for ksefpl_process_queue)
[ ] Test invoice submitted — ACCEPTED in audit log with KSeF-ID
[ ] UPO downloaded and stored in var/ksefpl/upo/
[ ] FA(2) XML reviewed for correct seller NIP and buyer data