Połączenie z KSeF
Łączysz konto z KSeF raz. To jedyny „straszny" krok — prowadzimy przez niego krok po kroku.
Przygotuj Stripe do zbierania danych faktury
Faktura KSeF to coś więcej niż sama kwota. Pola pochodzą z danych w Stripe, więc zanim zaczniesz składać, włącz kilka rzeczy w Stripe — to dzięki temu faktury płyną dalej, zamiast zostać wstrzymane:
- Zbieranie NIP-ów (Tax ID) — żeby NIP nabywcy (albo numer VAT UE / zagraniczny identyfikator podatkowy) trafił do
customer_tax_ids. To właśnie czyni z faktury fakturę B2B w KSeF. - Wymagany adres rozliczeniowy — żeby trafił adres nabywcy. Zidentyfikowany nabywca (taki z identyfikatorem podatkowym) wymaga adresu; bez niego wstrzymujemy fakturę, zamiast ją złożyć. Zobacz Odrzucenia i problemy.
- Nazwa klienta — żeby nabywca był wskazany na fakturze.
Jak to włączyć, zależy od sposobu fakturowania:
| Fakturujesz przez | Gdzie to włączyć |
|---|---|
| Checkout / API / Billing | W ustawieniach Checkout Session / Customer: włącz Tax ID collection i ustaw adres rozliczeniowy jako wymagany; zbieraj nazwę klienta. |
| Payment Links (bez kodu) | Na Płatności (Payment Link) w panelu włącz Collect tax IDs oraz Collect customers' addresses i wymagaj nazwy. |
Wskazówka — webhook jest automatyczny. Aplikacja Stripe konfiguruje go przy instalacji, więc nie musisz nic ustawiać w Stripe Developers. Włączasz tylko powyższe przełączniki zbierania danych.
Token czy certyfikat KSeF
Dwie metody uwierzytelnienia — obie generujesz w aplikacji podatnika KSeF, obie przechowujemy zaszyfrowane:
| Metoda | Co podajesz | Kiedy |
|---|---|---|
| Token KSeF | token maszyna-maszyna | najszybszy start — jedno pole do wklejenia |
| Certyfikat KSeF | certyfikat + klucz prywatny (PEM) | rozwiązanie docelowe Ministerstwa Finansów |
Certyfikat KSeF jest darmowy, wydaje go Ministerstwo Finansów i jest ważny do 2 lat. Zamiast wysyłać sekret przy każdym logowaniu, podpisujesz nim wyzwanie (XAdES) — sam klucz prywatny nigdy nie trafia do KSeF. Ta sama ścieżka przyjmuje certyfikat z Twojego podpisu kwalifikowanego, o ile możesz wyeksportować klucz.
Przy certyfikacie wymagane są oba bloki PEM — bez nich nie zapiszemy połączenia.
Planowo — Ministerstwo Finansów zapowiedziało, że tokeny działają do 31 grudnia 2026 r., a od 1 stycznia 2027 r. zostaną same certyfikaty. W czerwcu 2026 r. MF zaproponowało jednak pozostawienie tokenów na stałe i na razie nie ma rozstrzygnięcia. Obie metody wspieramy i żadnej nie wycofujemy; jeśli wybierasz dziś od zera, certyfikat jest bezpieczniejszym wyborem.
Najpierw TEST
Środowisko TEST jest zaznaczone domyślnie. Przypadkowe PROD to koszmar, więc wybór środowiska jest pierwszy i świadomy. Na TEST składasz do piaskownicy KSeF — żadnych skutków prawnych, idealne do sprawdzenia konfiguracji.
Ważne — Stripe dostarcza zdarzenia z trybu testowego i z trybu live osobno. Ćwicz na fakturach z trybu testowego Stripe, gdy KSeF jest na TEST, żeby dane testowe nigdy nie przeszły do KSeF na PROD. Twoje prawdziwe faktury z trybu live to te, które się składają, gdy przełączysz KSeF na PROD.
Testuj połączenie
Przycisk „Testuj połączenie" próbuje uwierzytelnić się w wybranym środowisku Twoją metodą (token lub XAdES). Zwraca tylko sukces albo porażkę — nigdy nie psuje formularza. Użyj go, zanim zapiszesz.
Przejście na PROD
Gdy faktury testowe działają, przełącz środowisko na PROD. Przejście wymaga jawnego potwierdzenia — to nieodwracalne skutki prawne. Nigdy nie składamy sztucznej, przykładowej faktury na produkcji, więc na świeżym koncie PROD, gdy nie ma nic do złożenia, widzisz po prostu spokojny stan „Jesteś na żywo"; Twoja pierwsza prawdziwa faktura ze Stripe składa się automatycznie. Pełną ścieżkę przejścia i listę gotowości znajdziesz w Przejściu na produkcję.
Wygasł token? Połącz ponownie
Gdy KSeF odrzuci z powodu nieaktualnego klucza (kod 21470), wygeneruj nowy token i wklej go ponownie w ustawieniach połączenia. Pola sekretów są zapisywalne tylko (puste w formularzu) — pozostawienie pustego pola nie nadpisze zapisanego sekretu. Zobacz Odrzucenia i problemy.