KSeF dla programistów: Stripe + polskie faktury bez budowania integracji

Stripe ma świetne API, bogate webhooks i gotowe rozwiązania do płatności (Checkout, Billing, Payment Links). Dostajesz kwotę, walutę, dane klienta, billing details, tax ID (NIP). Ale te dane to input, nie output. Żaden webhook Stripe nie generuje polskiej faktury VAT.

Stripe oferuje Stripe Invoicing, ale generuje ono dokumenty PDF w anglosaskim formacie. Nie obsługuje polskich stawek VAT (ZW, NP, 8%), nie formatuje NIP-u zgodnie z polskimi wymogami i nie komunikuje się z KSeF. Od 2026 roku każda faktura B2B w Polsce musi trafić do KSeF w formacie XML FA(2). PDF ze Stripe tego wymogu nie spełnia.

Między webhookiem Stripe a fakturą w KSeF jest przepaść. Musisz ją zasypać kodem, albo użyć gotowego rozwiązania, które zrobi to za Ciebie. Stripto jest takim rozwiązaniem: łączy Stripe z Fakturownią, inFakt lub wFirma, które wystawiają polskie faktury VAT i wysyłają je do KSeF automatycznie.

KSeF to Krajowy System e-Faktur prowadzony przez Ministerstwo Finansów. Udostępnia REST API do wystawiania, odbierania i weryfikacji faktur ustrukturyzowanych. Brzmi prosto, ale w praktyce integracja jest znacznie bardziej skomplikowana niż typowe REST API, do których jesteś przyzwyczajony.

Autoryzacja i tokeny

KSeF API wymaga autoryzacji tokenem sesyjnym. Żeby go uzyskać, musisz się uwierzytelnić jedną z metod: podpisem zaufanym (interaktywny, nie da się zautomatyzować), podpisem kwalifikowanym (fizyczny token USB) lub pieczęcią kwalifikowaną (jedyna opcja do automatyzacji M2M, wymaga zakupu certyfikatu od kwalifikowanego dostawcy). Token sesyjny ma ograniczony czas życia i musisz implementować odświeżanie i obsługę wygaśnięcia.

Format XML FA(2)

Faktura ustrukturyzowana to plik XML zgodny ze schematem FA(2) opublikowanym przez Ministerstwo Finansów. Schemat definiuje ponad 300 pól z rygorystyczną walidacją. Pominięcie wymaganego elementu, zły format daty czy niepoprawny NIP, i walidacja odrzuca całą fakturę. Musisz znać schemat XSD i walidować każdą wygenerowaną fakturę przed wysyłką.

UPO (Urzędowe Poświadczenie Odbioru)

Po przyjęciu faktury KSeF zwraca UPO z unikalnym numerem KSeF i timestampem. Wysyłka i potwierdzenie to osobne endpointy (asynchroniczne). Musisz implementować polling, przechowywać UPO i obsłużyć scenariusz, gdy UPO nie przychodzi (timeout, awaria KSeF).

Tryb offline

KSeF może być chwilowo niedostępny. W takim przypadku fakturę trzeba wystawić w trybie awaryjnym i wysłać do KSeF po przywróceniu systemu. To kolejna warstwa logiki: kolejkowanie faktur, automatyczne wysyłanie po powrocie KSeF online, obsługa kolizji numerów.

Jeśli chcesz zbudować integrację Stripe → KSeF sam, musisz zaimplementować cały pipeline od odbioru płatności po wystawienie faktury w KSeF. Oto poszczególne komponenty:

1. Odbiór webhooków Stripe

Endpoint przyjmujący zdarzenia ze Stripe. Musisz zdecydować, na które zdarzenia reagujesz (checkout.session.completed, invoice.paid, charge.succeeded), weryfikować sygnatury webhooków, implementować idempotency (żeby ten sam webhook przetworzony dwukrotnie nie wystawił duplikatu faktury) i obsługiwać retry Stripe.

2. Parsowanie danych kupującego

Wyciągnięcie NIP-u (z customer.tax_ids lub custom_fields), nazwy firmy, adresu z billing details, opisu pozycji z line items. Obsługa brakujących danych (klient nie podał NIP-u, brak adresu). Mapowanie danych ze Stripe na pola wymagane przez KSeF (inne nazwy, inne formaty).

3. Generowanie XML FA(2)

Budowanie poprawnego XML-a zgodnego ze schematem XSD. Mapowanie kwot (Stripe podaje kwoty w groszach), walut, stawek VAT, dat. Walidacja przeciwko XSD przed wysyłką. Obsługa różnych typów faktur (jednorazowe, subskrypcyjne, korekty).

4. Autoryzacja i wysyłka do KSeF

Uzyskanie tokenu sesyjnego, odświeżanie, przechowywanie certyfikatu. POST do KSeF API, polling po numer KSeF i UPO. Obsługa statusów: faktura przyjęta, odrzucona, w trakcie przetwarzania. Tryb offline, gdy KSeF jest niedostępny.

5. Obsługa błędów i monitoring

Błędy walidacji XML, timeouty KSeF, exponential backoff, kolejkowanie. Plus monitoring i alerty, bo musisz wiedzieć, gdy faktura nie przeszła. Każda niewystawiona faktura to potencjalna kara od Ministerstwa Finansów.

6. Utrzymanie

Schemat FA(2) się zmienia. Ministerstwo Finansów publikuje nowe wersje XSD. API KSeF ewoluuje. Musisz śledzić zmiany i aktualizować generator XML-a. To nie jest „zbuduj i zapomnij". To ciągła odpowiedzialność.

Na podstawie publicznych postmortemów i naszego własnego doświadczenia z integracją Stripe z polskim ekosystemem księgowym, oto realne oszacowanie pracy:

Stripto eliminuje cały pipeline opisany powyżej. Nie musisz pisać webhook listenera, parsować danych Stripe, generować XML-a, autoryzować się w KSeF ani implementować retry. Podłączasz Stripe do Stripto, Stripto podłączasz do Fakturowni lub inFakt i od tego momentu każda płatność automatycznie generuje polską fakturę VAT gotową na KSeF.

Jako programista docenisz, że Stripto nie wymaga żadnych zmian w Twoim kodzie. Twoje webhooks, Checkout Sessions, Payment Links, subskrypcje Stripe Billing, wszystko działa dalej tak jak dotychczas. Stripto nasłuchuje płatności równolegle, niezależnie od Twojej aplikacji. Nie musisz dodawać nowych endpointów, nie musisz modyfikować flow płatności.

Stripto obsługuje za Ciebie wszystkie edge cases, na które tracisz czas przy samodzielnej integracji: duplikaty webhooków, brakujący NIP, subskrypcje z prorating, kupony, częściowe zwroty, płatności w walutach obcych. Każdy z tych scenariuszy to potencjalny bug w Twojej integracji. W Stripto są obsłużone i przetestowane.

Konfiguracja trwa kilka minut: połącz konto Stripe przez OAuth, podaj klucz API Fakturowni, inFakt lub wFirma, ustaw domyślną stawkę VAT. 5 pierwszych transakcji za darmo, bez podpinania karty. Możesz przetestować integrację na prawdziwych płatnościach zanim zdecydujesz się na płatny plan.

Stripto celowo nie komunikuje się bezpośrednio z KSeF API. Zamiast tego deleguje wystawianie faktur do Fakturowni lub inFakt, czyli programów księgowych, które od lat obsługują KSeF, mają sprawdzoną walidację XML i zarządzanie tokenami. To świadoma decyzja architektoniczna.

Dlaczego? Bo KSeF API to jeden z najtrudniejszych systemów rządowych do integracji. Schemat XML zmienia się, środowisko testowe bywa niestabilne, autoryzacja wymaga pieczęci kwalifikowanej do automatyzacji M2M. Fakturownia, inFakt i wFirma mają dedykowane zespoły, które śledzą zmiany MF i aktualizują swoje integracje. Budując na ich API, Stripto nie musi duplikować tej pracy.

Dla Ciebie jako programisty to oznacza, że KSeF jest w pełni abstrakcją za Fakturownią, inFakt lub wFirma. Nie musisz znać schematu FA(2), nie musisz kupować pieczęci kwalifikowanej, nie musisz implementować polling UPO. Stripto tworzy fakturę przez API programu księgowego, a ten zajmuje się resztą: walidacja XML, wysyłka do KSeF, pobranie UPO, obsługa trybu offline.

Architektura wygląda tak: płatność w Stripe → webhook do Stripto → Stripto parsuje dane i tworzy fakturę przez API Fakturowni, inFakt lub wFirma → program księgowy generuje XML FA(2) i wysyła do KSeF → KSeF zwraca UPO. Cały pipeline działa automatycznie, w kilka sekund od płatności.

Poniżej lista scenariuszy, które musisz obsłużyć w samodzielnej integracji i które Stripto obsługuje automatycznie. Każdy z nich to potencjalny bug, edge case i dodatkowe godziny developmentu.

Typy płatności Stripe

Stripe Checkout (jednorazowe i subskrypcyjne), Payment Links, subskrypcje Stripe Billing (odnowienia, upgrade, downgrade, trial, kupony), płatności przez API. Stripto obsługuje je wszystkie z jedną konfiguracją. W samodzielnej integracji musisz obsłużyć każdy typ zdarzenia osobno.

Parsowanie NIP-u

Stripe przechowuje NIP w kilku miejscach: custom_fields z kluczem „nip", customer_details.tax_ids z typem pl_vat, customer.tax_ids na obiekcie Customer. Stripto sprawdza wszystkie te źródła w odpowiedniej kolejności. W samodzielnej integracji musisz sam zaimplementować tę logikę i obsłużyć przypadek, gdy NIP jest w innym formacie (z myślnikami, ze spacjami, z prefiksem PL).

Ochrona przed duplikatami

Stripe może wysłać ten sam webhook wielokrotnie (retry przy timeout). Bez idempotency check dostaniesz duplikaty faktur w programie księgowym. Stripto sprawdza każdą transakcję przed wystawieniem faktury. Jeśli faktura za daną płatność już istnieje, druga nie zostanie wystawiona. Przy subskrypcjach to szczególnie ważne, bo retries zdarzają się częściej.

Mapowanie danych na fakturę

Kwota (grosze → złotówki), waluta, nazwa produktu, ilość, stawka VAT, dane kupującego, dane sprzedawcy. Przy subskrypcjach: obsługa proratingu (proporcjonalne rozliczenie przy zmianie planu), kuponów, wielu pozycji (subscription items). Stripto mapuje to wszystko automatycznie.

Waluty obce

Jeśli przyjmujesz płatności w EUR, USD lub GBP, faktura musi być wystawiona w walucie transakcji, a przeliczenie na PLN do celów VAT odbywa się po kursie NBP. Stripto przekazuje walutę do Fakturowni, inFakt lub wFirma, które automatycznie pobierają kurs NBP. W samodzielnej integracji musisz sam pobierać kursy i pilnować prawidłowej daty kursu.

Historyczne transakcje

Jeśli podłączasz integrację do istniejącego konta Stripe z setkami transakcji, Stripto pozwala wystawić faktury za wcześniejsze płatności. Synchronizuje historyczne transakcje ze Stripe, więc nie musisz ręcznie przeglądać historii. W samodzielnej integracji musisz to zaimplementować od zera.

Obsługa błędów

Wygasły klucz API Fakturowni, timeout, odrzucona faktura (np. brakujące pole). Stripto zapisuje błędy w panelu, automatycznie ponawia próbę przy błędach tymczasowych i pozwala ręcznie powtórzyć synchronizację jednym kliknięciem. W samodzielnej integracji musisz zaimplementować retry logic, kolejkowanie i alerting.

Uczciwa odpowiedź: zależy od Twojego scenariusza. Oto tabela, która pomoże Ci podjąć decyzję:

Konfiguracja nie wymaga pisania kodu ani zmian w Twoim systemie płatności. Całość zajmuje kilka minut.

Rejestrujesz się w Stripto i podłączasz konto Stripe jednym kliknięciem przez OAuth. Stripto automatycznie tworzy webhook nasłuchujący na zdarzenia płatności. Nie musisz ręcznie konfigurować endpointów ani zarządzać sekretami webhooków.

Podajesz klucz API Fakturowni (Ustawienia → API → Token API + domena konta) lub inFakt (Ustawienia → Integracje → Klucz API). Stripto weryfikuje połączenie i od tego momentu każda płatność automatycznie generuje fakturę VAT.

Ustawiasz domyślną stawkę VAT (np. 23%) i opcjonalnie konfigurację nazw produktów na fakturach. 5 pierwszych transakcji jest za darmo, bez podpinania karty. Plany zaczynają się od 19 zł/mies. (od 190 zł/rok).

Warto upewnić się, że Stripe Checkout zbiera NIP i adres od klientów. Dodaj pole NIP jako custom field i włącz zbieranie adresu rozliczeniowego. Szczegóły w artykule faktury za Stripe Checkout.

Instrukcje konfiguracji dla konkretnych programów: Stripe + Fakturownia i Stripe + inFakt. Przewodnik łączenia z KSeF: jak połączyć Stripe z KSeF.