KSeF (Polish e-Invoicing) - User Guide

What is KSeF?

KSeF (Krajowy System e-Faktur) is Poland's National e-Invoice System. It is a government-mandated platform for issuing, receiving, and storing structured electronic invoices. Younium integrates with KSeF through the Maventa e-invoicing network, so your invoices are automatically submitted to the Polish tax authority when posted.

Prerequisites

Before enabling KSeF in Younium, ensure the following are in place:

1. Maventa / AutoInvoice Configuration

KSeF submission uses the Maventa e-invoicing network. Your legal entity must already have AutoInvoice (Maventa) configured and working. If you haven't set up AutoInvoice yet, contact Younium support for assistance.

2. Legal Entity Information

Your legal entity in Younium must have the following fields filled in:

Field	Requirement
Tax Registration Number	Polish NIP in the format `PL` followed by exactly 10 digits (e.g. `PL1234567890`)
Organization Number	Polish NIP in the format `PL` followed by exactly 10 digits (e.g. `PL1234567890`)
Bank Account or IBAN	At least one must be provided
BIC	Required
Street Address	Required
City	Required
Zip Code	Required
Country	Required

3. KSeF Authorization Token

You need to obtain an authorization token from the Polish KSeF government portal. This token authorizes Younium (via Maventa) to submit invoices on your behalf.

Note: When KSeF tokens expire you will need to obtain a new token and update it in Younium.

4. Recipient (Account) Requirements

For each account you send invoices to via KSeF, all of the following must be true:

Organization Number is set and matches the Polish NIP format: PL + 10 digits.
Electronic Invoice Address (EIA) is set and matches the Polish NIP format: PL + 10 digits — this becomes the EndpointID in the KSeF submission.
Electronic Invoice Address Scheme is either empty (Younium will populate 9945 automatically) or already set to 9945. Any other scheme is rejected.
Tax Registration Number is optional, but if provided it must match the Polish NIP format.

Setup Steps

Step 1: Enable KSeF on Your Legal Entity

Contact Younium support to enable the KSeF feature flag on your legal entity. This is a one-time setup performed by the Younium team.

Step 2: Open KSeF Settings

Navigate to Settings > Integrations > KSeF in the Younium application.

Step 3: Select Environment

Choose the appropriate environment:

Test — for testing with the KSeF staging environment
Production — for live invoice submission to the Polish tax authority

Step 4: Enter Your KSeF Token

Paste the authorization token you obtained from the Polish KSeF government portal.

Step 5: Save Settings

Click Save. The integration will activate automatically when both the KSeF toggle is enabled and a valid token is provided. Younium will also automatically register a webhook to receive real-time status updates from Maventa.

Step 6: Validate Your Legal Entity

Ensure all required fields from the prerequisites are filled in on your legal entity. The system checks all fields listed in the prerequisites and reports any missing information.

How It Works

Once KSeF is enabled and configured:

Invoice Posting — When you post an invoice for a Polish recipient, Younium automatically submits it to KSeF through the Maventa network. No additional action is required from you.
KSeF ID Assignment — The Polish tax authority assigns a unique KSeF ID to each accepted invoice. This ID is stored in Younium and visible in the invoice details. The format looks like: 1234567890-20260402-XXXXXXXXXXXX-XX.
Official Acknowledgment (UPO) — The UPO (Urzedowe Potwierdzenie Odbioru) is an official government receipt confirming that KSeF has accepted your invoice. It is automatically downloaded and stored in Younium.
Status Updates — Invoice statuses are updated automatically through:
- Real-time webhooks from Maventa (immediate notification)
- Periodic polling (every 30 minutes as a fallback)

You can check the KSeF status of any invoice by viewing its details in Younium.

Invoice Status Lifecycle

Status	Meaning
Pending	Invoice is being prepared for submission
Submitted	Invoice has been sent to Maventa and is awaiting KSeF processing
Processed	KSeF has accepted the invoice and assigned a KSeF ID
Failed	Submission or processing failed (see error message for details)

Token Management

When your token expires or you want to submit new one:

Obtain a new token from the Polish KSeF government portal
Go to Settings > Integrations > KSeF
Click Edit > paste the new token and Submit Token to Maventa
Save your settings

Important: Invoices posted while the token is expired will fail to submit to KSeF. Ensure you renew your token before it expires.

Supported Invoice Flows

KSeF tracking is automatically applied when invoices are sent through any of these methods:

Standard invoice posting (Post Invoice)
Electronic invoice delivery (e-Invoice, External Print, Automatic Electronic Routing)
Invoice resend (Resend Electronic Invoice)

Troubleshooting

"KSeF validation failed"

Younium validates KSeF requirements before submitting to Maventa. If any field is missing, in the wrong format, or contains a value KSeF does not accept, posting fails with a single error message listing every issue found. Typical causes:

On the sender (legal entity):

Tax Registration Number is empty or not in PL + 10-digit format.
Organization Number is empty or not in PL + 10-digit format.
BIC is empty or not a valid SWIFT/BIC code (8 or 11 uppercase characters, e.g. INGBPLPW or INGBPLPWXXX).

On the recipient (account):

Organization Number is empty or not in PL + 10-digit format.
Electronic Invoice Address is empty or not in PL + 10-digit format.
Electronic Invoice Address Scheme is set to something other than 9945.
Tax Registration Number is present but not in PL + 10-digit format.

On the invoice lines:

VAT rate on one or more lines is not a valid KSeF rate. Allowed numeric rates are 0, 3, 4, 5, 7, 8, 22, 23 (percent). For exempt, reverse-charge, or not-subject lines (zw, oo, np, 0 KR/WDT/EX), configure the appropriate tax category on the product/charge instead of using a custom percentage.

Fix all reported issues and re-post the invoice. The error message returned by Younium lists each specific field and its current value, so you can correct them directly without trial-and-error.

Invoice not appearing in KSeF

Confirm the KSeF integration is active (Settings > Integrations > KSeF shows "Active")
Verify the legal entity has the KSeF feature flag enabled
Check if the invoice status shows "Failed" with an error message

Token expired

Obtain a new token from the KSeF government portal
Use the Submit Token to Maventa button in KSeF settings
Previously failed invoices can be resent after the token is renewed

FAQ

Q: Do I need to do anything special when posting invoices?
A: No. Once KSeF is configured, invoice submission happens automatically when you post invoices. There are no additional steps.

Q: Can I use KSeF in test mode first?
A: Yes. Select the "Test" environment in KSeF settings to submit invoices to the KSeF staging environment. Switch to "Production" when you're ready to go live.

Q: What happens if KSeF submission fails?
A: The invoice is still posted in Younium. The KSeF entry will show a "Failed" status with an error message. You can resend the invoice after resolving the issue.

Q: Is the UPO stored permanently?
A: Yes. UPO documents are stored permanently in Younium as required by Polish regulations. They serve as official proof of invoice submission to KSeF.

Related to