Connecting KSeF
You link your account to KSeF once. It's the one "scary" step — we walk you through it.
Prepare Stripe to capture invoice data
A KSeF invoice needs more than an amount. The fields come from your Stripe data, so turn a few things on in Stripe before you file — it's what keeps invoices flowing instead of getting held:
- Tax ID collection — so the buyer's NIP (or EU VAT / foreign tax id) arrives in
customer_tax_ids. This is what makes an invoice a B2B KSeF invoice. - Required billing address — so the buyer's address arrives. An identified buyer (one with a tax id) requires an address; without one we hold the invoice instead of filing it. See Rejections & troubleshooting.
- Customer name — so the buyer is named on the invoice.
How you switch these on depends on how you bill:
| You bill with | Where to enable it |
|---|---|
| Checkout / API / Billing | In Checkout Session / Customer settings: enable Tax ID collection and set the billing address to required; collect the customer name. |
| Payment Links (no-code) | On the Payment Link in the Dashboard, turn on Collect tax IDs and Collect customers' addresses, and require a name. |
Tip — the webhook is automatic. The Stripe App wires it on install, so there's nothing to set up under Stripe Developers. You only enable the data-collection toggles above.
Token vs KSeF certificate
Two authentication methods — you get both from the KSeF taxpayer app, and we store both encrypted:
| Method | What you provide | When |
|---|---|---|
| KSeF token | a machine-to-machine token | fastest start — one field to paste |
| KSeF certificate | certificate + private key (PEM) | the Ministry of Finance's target method |
A KSeF certificate is free, issued by the Ministry of Finance, and valid for up to 2 years. Instead of sending a secret on every sign-in, you sign a challenge with it (XAdES) — the private key itself never reaches KSeF. The same path accepts the certificate from your qualified signature, as long as you can export the key.
The certificate method requires both PEM blocks — without them we won't persist the connection.
Planned — the Ministry of Finance has said tokens work until 31 December 2026, with certificates the only method from 1 January 2027. In June 2026 it then proposed keeping tokens permanently, and nothing is settled yet. We support both and are retiring neither; if you're choosing from scratch today, the certificate is the safer pick.
TEST first
The TEST environment is preselected. Accidental PROD is the nightmare, so the environment choice comes first and is deliberate. On TEST you file to the KSeF sandbox — no legal effect, perfect for verifying your setup.
Important — Stripe delivers test-mode and live-mode events separately. Rehearse with Stripe test-mode invoices while KSeF is on TEST, so test data never crosses into PROD KSeF. Your real, live-mode Stripe invoices are the ones that file once you switch KSeF to PROD.
Test connection
The "Test connection" button tries to authenticate against the chosen environment using your method (token or XAdES). It returns only success or failure — it never breaks the form. Use it before you save.
Switching to PROD
Once test invoices work, switch the environment to PROD. The switch requires an explicit confirmation — these are irreversible legal effects. We never file a synthetic sample into production, so on a fresh PROD account with nothing to file you simply see a calm "You're live" state; your first real Stripe invoice files automatically. For the full promotion path and the readiness checklist, see Going live.
Token expired? Reconnect
When KSeF rejects with a stale-key code (21470), generate a fresh token and paste it again in the connection settings. The secret fields are write-only (blank in the form) — leaving one blank will not overwrite the stored secret. See Rejections & troubleshooting.