Paired Mode — Dual-Channel Invoicing (WooCommerce)

KSeF Pro for WooCommerce can operate in Paired Mode alongside Fakturownia Pro for WooCommerce. A single WooCommerce order trigger sends the FA(2) XML to KSeF and creates a customer-facing PDF invoice in Fakturownia.pl simultaneously — with the official KSeF-ID embedded in the PDF.

Standalone vs. Paired Mode

| Aspect | Standalone KSeF Pro | Paired Mode | |---|---|---| | Government submission | Yes — FA(2) XML to KSeF | Yes — same | | Customer-facing PDF | No | Yes — Fakturownia Pro generates PDF | | KSeF-ID on customer PDF | N/A | Yes — automatically populated | | Configuration | KSeF Pro plugin only | Shared rule engine in KSeF Pro | | Fakturownia triggers | Fakturownia Pro manages its own | Overridden by KSeF Pro rule engine | | Failure modes | KSeF failure only | Per-channel discrepancy states | | Required plugins | KSeF Pro only | KSeF Pro + Fakturownia Pro | | WordPress cron dependency | Yes | Yes — both plugins use WP cron |

When NOT to use Paired Mode: If your accounting team manages Fakturownia manually or uses a third-party integration to create invoices, enabling Paired Mode will conflict with their workflow. Paired Mode gives KSeF Pro full control of when Fakturownia invoices are created.

Why Paired Mode?

KSeF is the government compliance channel. It accepts structured FA(2) XML and issues KSeF-IDs — but it does not send customer-facing documents. Your buyers still expect a PDF invoice in their inbox. Paired Mode bridges both requirements from a single order event.

| Channel | Plugin | Output | Recipient | |---|---|---|---| | Government | KSeF Pro | FA(2) XML → KSeF-ID + UPO | Ministry of Finance | | Customer | Fakturownia Pro WC | PDF invoice with KSeF-ID | Customer email / download portal |

Without Paired Mode, you must manually copy the KSeF-ID from the audit log and enter it into each Fakturownia invoice — not scalable beyond a handful of orders per day.

Requirements

KSeF Pro for WooCommerce — installed, connection verified, test submission completed
Fakturownia Pro for WooCommerce — version 3.0 or later, Fakturownia API token connected and verified
Both plugins using the same order status trigger (or Paired Mode overrides Fakturownia's trigger)
WordPress cron running reliably (system cron recommended — see below)

WordPress Cron Requirement

Both plugins rely on WordPress cron for their processing queues. WP-Cron only executes when a page is visited on your site. For stores with low traffic (or overnight quiet periods), this can cause significant delays in invoice processing.

Recommended: Replace WP-Cron with a real system cron job:

# Add to crontab (runs every minute):
*/1 * * * * curl -s https://yourstore.com/wp-cron.php?doing_wp_cron > /dev/null
# Or use WP-CLI:
*/1 * * * * /usr/local/bin/wp --path=/path/to/wordpress cron event run --due-now

With system cron in place, invoice processing happens within 60 seconds of the order reaching trigger status, regardless of site traffic.

Step-by-Step Setup

Phase 1: Verify each plugin independently

In KSeF Pro, test a submission: WooCommerce → KSeF Pro → Test Connection
Place a test order, set it to the trigger status, confirm ACCEPTED in the KSeF audit log
In Fakturownia Pro, test the API connection and generate a manual invoice for a test order
Confirm the invoice appears in your Fakturownia.pl account

Phase 2: Enable Paired Mode

Confirm Fakturownia Pro is installed and its connection shows green
Open WooCommerce → KSeF Pro → Invoice Settings
Enable the "Paired mode with Fakturownia Pro" toggle
Select trigger order (see below)
Save settings

Paired mode settings and dual-channel configuration

Phase 3: Test the full dual-channel flow

Place a new test order
Set it to the trigger status
Wait up to 5 minutes (WP cron + KSeF UPO time)
Check the KSeF audit log — confirm both KSEF_ID and FAKTUROWNIA_ID are populated
Check Fakturownia.pl — confirm the invoice has numer_ksef populated
Download the PDF — confirm the KSeF-ID appears under "KSeF numer"

Trigger Order

KSeF first (recommended)

KSeF Pro submits the FA(2) XML and waits for the permanent KSeF-ID (UPO downloaded) before passing control to Fakturownia Pro. The Fakturownia invoice is created with numer_ksef populated from the start.

Trade-off: the customer PDF is delayed by 1–3 minutes (KSeF UPO processing time). For most B2B workflows this is acceptable — the customer receives their invoice within a few minutes of order confirmation.

Simultaneous

Both submissions fire independently via WordPress cron. The Fakturownia invoice is created immediately — the customer gets their PDF at once. The KSeF-ID is backfilled into the Fakturownia invoice via an update API call once the UPO arrives.

Requires Fakturownia Pro WC 3.2+ for the backfill update call. Use when customer PDF delivery time is more important than having the KSeF-ID on the first-issued PDF.

Shared Rule Engine

In Paired Mode both plugins share a unified rule engine. Configure it once under WooCommerce → KSeF Pro → Invoice Settings → Rule Engine:

| Decision | Shared Rule Controls | Separate Before Paired Mode | |---|---|---| | Order status trigger | One setting for both | Configured separately per plugin | | B2B vs B2C detection | NIP present in order meta | Each plugin checked separately | | VAT rate mapping | One tax class → code table | Separate mapping per plugin | | Currency rules | Shared PLN conversion | Separate per plugin | | Payment method conditions | One condition set | Separate per plugin |

After enabling Paired Mode, Fakturownia Pro's own trigger settings are overridden. All triggering is controlled by KSeF Pro's rule engine.

What Happens When a Rule Fires

The full sequence for "KSeF first" mode, from order status change to customer PDF:

WooCommerce order reaches trigger status
            ↓
    KSeF Pro rule engine evaluates order
            ↓
    ┌──────────────────────────┐
    │       KSeF Pro           │
    │ 1. Generate FA(2) XML    │
    │ 2. Sign (XAdES-BES)      │
    │ 3. Queue job             │
    │ 4. (cron) Open session   │
    │ 5. Submit XML            │
    │ 6. Close session         │
    │ 7. Poll for UPO          │
    │ 8. Download UPO          │
    │ 9. Store KSeF-ID         │
    │ 10. Signal Fakturownia ──│──┐
    └──────────────────────────┘  │
                                  ↓
    ┌──────────────────────────────────────┐
    │       Fakturownia Pro WC             │
    │ 1. Receive KSeF-ID signal            │
    │ 2. Create Fakturownia invoice via API│
    │ 3. Set numer_ksef = KSeF-ID          │
    │ 4. PDF generated with KSeF-ID        │
    │ 5. Email sent to customer            │
    └──────────────────────────────────────┘

The WooCommerce action hooks involved are: woocommerce_order_status_changed fires the KSeF Pro queue job; ksefpl_ksef_id_received (custom action) fires the Fakturownia Pro invoice creation. Both are WordPress actions processed via WP cron.

KSeF-ID on Customer PDF

When Fakturownia Pro creates the customer invoice, it receives the KSeF-ID from KSeF Pro and stores it in the Fakturownia document's numer_ksef field. The Fakturownia.pl default invoice template displays this as "KSeF numer" under the invoice header.

If you use a custom Fakturownia invoice template, add the {numer_ksef} merge tag to display the KSeF-ID. Customers can use this number to:

Verify the invoice at https://ksef.mf.gov.pl (public verification endpoint — no login required)
Import the document into their own accounting software via the KSeF API
Reference it in VAT return filings and during audits

Discrepancy States and Recovery

When one channel fails, KSeF Pro logs the discrepancy:

| State | Meaning | Recovery Action | |---|---|---| | KSEF_OK_FAKTUROWNIA_FAILED | KSeF accepted; Fakturownia API error | Retry Fakturownia leg from audit log | | KSEF_FAILED_FAKTUROWNIA_SKIPPED | KSeF failed; Fakturownia blocked | Fix KSeF error, retry both from audit log | | KSEF_OK_FAKTUROWNIA_PENDING | KSeF accepted; Fakturownia not yet triggered | Normal for simultaneous mode — wait | | KSEF_ID_BACKFILL_FAILED | KSeF-ID received; Fakturownia update call failed | Re-run backfill via WP-CLI or audit log |

Retry Fakturownia Leg Only

To re-trigger only the Fakturownia submission for an already-accepted KSeF record (without re-submitting to the government):

WooCommerce → KSeF Pro → Audit Log → filter by KSEF_OK_FAKTUROWNIA_FAILED
Select the affected orders
Click "Retry Fakturownia leg"

Or via WP-CLI:

wp ksefpl retry-fakturownia --order-id=1001

This creates a new Fakturownia invoice using the stored KSeF-ID — no new KSeF session is opened.

FAQ

Do I need both plugins?

No. KSeF Pro works alone for government compliance. Fakturownia Pro works alone for customer PDF invoicing. Paired Mode automates the connection between them when you need both.

What if KSeF is down but Fakturownia is working?

In "KSeF first" mode: Fakturownia invoice creation is blocked. The order remains in KSEF_FAILED_FAKTUROWNIA_SKIPPED state until KSeF recovers and you retry.

In "Simultaneous" mode: Fakturownia creates the invoice immediately. The customer receives a PDF without a KSeF-ID. The ID is backfilled once KSeF comes back online and the UPO is downloaded.

KSeF maintenance windows (typically Sunday 00:00–06:00 CET) are predictable. For stores with significant Sunday volume, Simultaneous mode avoids customer-facing delays during these windows.

What if Fakturownia is down but KSeF is working?

KSeF accepts the submission normally. The Fakturownia leg fails and logs as KSEF_OK_FAKTUROWNIA_FAILED. Once Fakturownia is available, retry the Fakturownia leg from the audit log using the already-stored KSeF-ID.

Will enabling Paired Mode affect invoices already generated by Fakturownia Pro?

No. Enabling Paired Mode affects only new order processing going forward. Existing Fakturownia invoices are not modified. Existing KSeF audit log records without Fakturownia IDs are not retroactively backfilled.

Correction Invoices in Paired Mode

When a correction is needed on an already-submitted invoice:

Click "Issue correction" in the order's KSeF Pro meta box
KSeF Pro generates an FA(2) KOR document referencing the original KSeF-ID
After the correction KSeF-ID is returned via UPO, Fakturownia Pro creates a credit note (korekta) referencing the original Fakturownia invoice
The customer receives a credit note PDF with the correction KSeF-ID

Both the original and correction appear as linked pairs in the audit log.

Paired Mode with WooCommerce Subscriptions

For stores using WooCommerce Subscriptions:

Each renewal order is treated independently — the rule engine evaluates it on status change just like a regular order
Renewal orders get their own KSeF-IDs and Fakturownia invoices
Cancellation refunds trigger the correction flow (KOR + credit note) if the subscription's last renewal invoice is on record

Cross-Platform Accounts

If you also run PrestaShop or Magento 2 stores with KSeF Pro, all platforms share the same KSeF account and NIP. The KSeF-ID sequence is unified across all storefronts:

Each platform has its own Fakturownia Pro instance and department assignment in Fakturownia.pl.