Płatności, KSeF i integracje API

Co najczęściej trzeba połączyć w polskiej firmie

Integracja API to ustalenie, który system jest źródłem prawdy dla danej informacji, i przeniesienie jej dalej bez ręcznego przepisywania. W polskiej firmie chodzi zwykle o pięć punktów: sklep, płatności, fakturowanie, CRM oraz magazyn i wysyłkę.

Zaczyna się najczęściej od jednego zdania: „po zapłacie ma się dziać reszta”. Reszta to konkretna lista zdarzeń. Zamówienie zmienia status, klient dostaje dokument, w CRM powstaje kontakt i zadanie, a magazyn rezerwuje towar albo kurier dostaje zlecenie.

Zanim cokolwiek zbuduję, sprawdzam, czy każdy z tych systemów ma API lub webhooki i co dokładnie potrafi. Sporo narzędzi udostępnia dane tylko do odczytu albo ma limit zapytań, który wyklucza synchronizację co minutę.

Nie wszystko warto łączyć. Proces uruchamiany dwa razy w tygodniu po trzy minuty zajmuje około pięciu godzin rocznie. Integracja kosztuje od 2000 zł netto plus utrzymanie, więc w takim przypadku proponuję eksport pliku albo przepływ w n8n.

• Sklep lub aplikacjaŹródło zamówienia: koszyk, dane klienta, wariant i kwota. Tu powstaje identyfikator, po którym rozpoznasz tę samą transakcję w pozostałych systemach.
• Bramka płatnościPotwierdza, że pieniądze wpłynęły, i jako jedyna ma prawo to potwierdzić. Zielony ekran po powrocie z banku nie jest dowodem zapłaty.
• FakturowanieDokument powstaje z danych zamówienia. Numeracja, stawki VAT i dane nabywcy muszą mieć jedno źródło, inaczej księgowość dostaje dwa równoległe zbiory dokumentów.
• CRM i marketingKontakt, źródło pozyskania, wartość zamówienia i zadanie dla handlowca. Tu powstają duplikaty, więc ustalamy klucz dopasowania: e-mail, NIP albo identyfikator klienta.
• Magazyn i wysyłkaStan magazynowy, rezerwacja, list przewozowy i numer paczki wracający do klienta. Przy sprzedaży w kilku kanałach stan musi mieć jedno źródło, inaczej ten sam towar sprzeda się dwa razy.

Cenniki dostawców i przepisy się zmieniają, więc przed decyzją sprawdź je u źródła.

KSeF w sklepie i aplikacji: program fakturowy czy własne API

Połączenie sprzedaży z KSeF oznacza, że opłacone zamówienie tworzy fakturę, dokument trafia do Krajowego Systemu e-Faktur, a jego numer wraca do zamówienia. Są dwie drogi: program fakturowy, który sam wysyła dokumenty do systemu, albo własne połączenie z API Ministerstwa Finansów. Najwięcej pracy wymagają dane nabywcy i obsługa odrzuconych dokumentów.

Obowiązek wystawiania e-faktur objął od 1 lutego 2026 r. firmy ze sprzedażą powyżej 200 mln zł w 2024 r., a od 1 kwietnia 2026 r. pozostałych przedsiębiorców. Do końca 2026 r. poza systemem może zostać firma, której faktury objęte obowiązkiem nie przekraczają w miesiącu 10 000 zł z podatkiem; po przekroczeniu progu e-fakturą musi być już ta, która go przekroczyła, i każda następna. Od 1 lutego 2026 r. obowiązuje struktura FA(3) zamiast FA(2). Źródło: ksef.podatki.gov.pl.

Dla większości sklepów ważniejsza jest inna informacja: faktury dla osób fizycznych, które nie prowadzą działalności, mogą nadal powstawać poza systemem, a wystawienie ich jako e-faktur jest dobrowolne. Jeśli to zrobisz, dokument trzeba wydać klientowi w uzgodniony sposób, na przykład jako wydruk albo plik z kodem QR. NIP zebrany przed płatnością rozstrzyga więc, którą drogą pójdzie faktura.

Stripe Invoicing sam nie tworzy ani nie wysyła e-faktur do systemów państwowych, polskiego też nie; dokumentacja Stripe odsyła do aplikacji partnerów albo do własnej integracji opartej na webhookach. Fakturę wystawia zatem program, z którego korzysta Twoja księgowość, i to on przekazuje ją dalej. Mój kod dostarcza mu dane z potwierdzonej płatności i odbiera numer oraz status dokumentu.

Własne połączenie z API systemu w wersji 2.0 ma sens, gdy faktury powstają we własnym systemie, na przykład w aplikacji z abonamentami, albo gdy program fakturowy nie obsługuje Twojego przypadku. Ministerstwo publikuje kontrakt OpenAPI, przewodnik dla programistów na GitHubie i dwa środowiska bez skutków prawnych: testowe i przedprodukcyjne. Faktura w XML idzie zaszyfrowana w sesji, a po jej zamknięciu system przygotowuje zbiorcze UPO.

Do logowania aplikacji służy najczęściej token. Generuje go osoba uprawniona po jednorazowym uwierzytelnieniu podpisem XAdES, na przykład kwalifikowanym albo Profilem Zaufanym, i od razu nadaje mu stały zakres, choćby tylko wysyłanie faktur. Zmiana zakresu oznacza nowy token, a stary można w każdej chwili unieważnić. Traktuję go jak hasło do konta bankowego: trzymam w sejfie na sekrety, nigdy w kodzie.

Druga strona to faktury od dostawców. Można je pobierać z systemu prosto do własnego obiegu kosztów, a dokumentacja Ministerstwa zaleca do tego pobieranie przyrostowe: najwyżej 20 eksportów na godzinę i nie częściej niż co 15 minut dla jednego typu podmiotu. Po przekroczeniu limitu API odpowiada kodem 429 z informacją, ile odczekać. Szerzej piszę o tym w przewodniku jak zautomatyzować obieg faktur kosztowych.

Trzeba też zaplanować przerwy w działaniu systemu. Według tej samej dokumentacji fakturę wystawioną w trybie offline24 przesyła się najpóźniej następnego dnia roboczego, a po awarii ogłoszonej przez Ministerstwo w ciągu 7 dni roboczych od jej zakończenia; program musi wtedy nanieść na dokument dwa kody QR. Połączenie, które tego nie przewiduje, zostawia faktury w zawieszeniu.

Koszt zależy przede wszystkim od tego, kto wysyła dokument. Za integrację biorę 2000 –⁠ 9000 zł netto. W cenniku pokazuję przykład, w którym płatność Stripe aktualizuje zamówienie i wystawia fakturę w programie fakturowym: 4600 zł netto, bez zwrotów i korekt. Własne połączenie z API, z trybami offline, obsługą odrzuceń albo pobieraniem faktur kosztowych, to więcej pracy i wycena bliżej górnej granicy. Abonament programu fakturowego płacisz jego dostawcy.

Kiedy własny kod nie ma sensu: jeśli wystawiasz kilkanaście faktur miesięcznie ręcznie w programie fakturowym, jego wbudowana wysyłka w zupełności wystarczy. Programista przydaje się dopiero tam, gdzie dane do faktury trzeba pobrać z płatności, sklepu albo CRM. Techniczne szczegóły, od sesji po odrzucone dokumenty, opisuję w przewodniku połączenie z API e-faktur krok po kroku.

Czy przy Twoim sklepie, Stripe albo BaseLinkerze wystarczy program do faktur, czy potrzebna jest integracja, sprawdzisz w krótkim teście. Najlepiej zrób to przed 1 stycznia 2027 r. Jeśli prowadzisz biuro rachunkowe albo agencję i takie wdrożenia potrzebne są Twoim klientom, zobacz, co robię dla klientów biur rachunkowych i co robię dla klientów agencji.

• Program fakturowy z wbudowaną wysyłkąFakturownia według swojej strony przesyła każdą fakturę sprzedażową do systemu automatycznie, w inFakt wysyłka to jedno kliknięcie. Moja praca to przekazanie programowi danych z płatności i odebranie numeru. Najtańsza droga, gdy faktury i tak powstają w takim programie.
• Własne połączenie z APIFaktura powstaje w Twojej aplikacji i stamtąd idzie do systemu. Więcej pracy i utrzymania: token, szyfrowanie, tryby offline, limity zapytań i zmiany w API ogłaszane w dzienniku zmian, w zamian pełna kontrola nad dokumentem i jego statusem.
• Pobieranie faktur kosztowychOsobny przepływ: dokumenty od dostawców trafiają z systemu do Twojego obiegu albo arkusza. Ma sens, gdy kosztów jest dużo i ktoś dziś przepisuje je ręcznie.

Automatyczna faktura po płatności krok po kroku

Żeby płatność i faktura spinały się bez ręcznej pracy, kolejność jest zawsze ta sama. Zanim napiszę pierwszą linijkę, ustalam z Twoją księgowością dwie rzeczy: czy sprzedaż konsumencka wymaga u Ciebie kasy rejestrującej i kto wystawia dokument przy płatności ratalnej albo odroczonej. Bez odpowiedzi na te pytania tej części nie da się zaprojektować.

1. Potwierdzone zdarzenie płatnościDokument uruchamia potwierdzenie od operatora, a nie powrót klienta na stronę z podziękowaniem. Do tego momentu zamówienie czeka.
2. Komplet danych nabywcyNIP i pełne dane firmy zbieramy przed płatnością. Poprawianie nabywcy na wystawionym dokumencie oznacza korektę albo notę, czyli ręczną pracę księgowości.
3. Wystawienie w programie fakturowymProgram dostaje pozycje, stawki VAT, kwoty i identyfikator płatności. Numeracja zostaje po jego stronie, żeby nie powstały dwa źródła numerów.
4. Wysyłka do systemu i do klientaFaktura dla firmy idzie do systemu w strukturze FA(3), klient dostaje PDF albo link. Numer nadany przez system, UPO i status zapisuję przy zamówieniu, a dokument odrzucony trafia na listę do poprawy, zamiast zniknąć.
5. Zwroty i korektyKażdy zwrot pieniędzy ma odpowiednik w dokumentach. Ustalamy, co powstaje przy zwrocie częściowym, a co przy pełnym, zanim pierwszy klient o niego poprosi.

Integracja Stripe w Polsce: metody płatności, waluty i wypłaty

Stripe na polskim koncie obsługuje karty, BLIK, Przelewy24 oraz portfele Apple Pay, Google Pay i Link. Stawki i ograniczenia poniżej pochodzą z cennika Stripe dla Polski i z docs.stripe.com. Szerzej, razem z PayPalem w Stripe, zbieraniem NIP-u w kasie i KSeF, piszę o tym w przewodniku Stripe w Polsce: prowizja, BLIK i faktury.

Cennik Stripe dla firmy z Polski (stripe.com/pl/pricing) wygląda tak: karty wydane w EOG 1,5% + 1,00 zł, karty premium z EOG 1,9% + 1,00 zł, karty brytyjskie 2,5% + 1,00 zł, pozostałe zagraniczne 3,25% + 1,00 zł. Gdy transakcja wymaga przewalutowania, dochodzi 2%. BLIK kosztuje 1,6% + 1,00 zł, a Przelewy24 uruchomione przez Stripe 1,9% + 1,00 zł.

Według dokumentacji Stripe BLIK rozlicza się wyłącznie w złotych i działa dla klientów w Polsce. Kod z aplikacji banku jest ważny dwie minuty, a na zatwierdzenie płatności klient ma 60 sekund. Metoda obsługuje zwroty pełne i częściowe oraz reklamacje, w których na dowody masz 12 dni kalendarzowych. BLIK można też zapisać do kolejnych obciążeń, ale ta opcja ma własne warunki i limity, które sprawdzam w dokumentacji przed projektem abonamentu.

Przelewy24 uruchomione przez Stripe mają według jego dokumentacji dwa ograniczenia, które potrafią wywrócić projekt subskrypcyjny. Nie obsługują płatności cyklicznych, więc tej metody nie zapiszesz do kolejnych obciążeń. Zwrot zlecisz do 180 dni od płatności, ale idzie on osobnym przelewem do trzech dni roboczych i na wyciągu klienta wygląda jak uznanie z opisem pierwotnej transakcji, a nie jak zwrot.

Pieniądze trafiają na firmowe konto z opóźnieniem, które trzeba wpisać w plan finansowy. Według dokumentacji wypłat pierwszą wypłatę Stripe planuje zwykle 7–⁠14 dni po pierwszej prawdziwej płatności, a na starcie środki z transakcji są dostępne po 7 dniach kalendarzowych. Docelowo cykl skraca się do 3 dni roboczych, choć przy podwyższonym ryzyku konto może zostać przy dłuższym. Wypłata standardowa nic nie kosztuje, minimalna kwota to 5 zł, a ekspresowa kosztuje 1% kwoty, co najmniej 2 zł.

Portfele mają własny warunek, opisany w dokumentacji rejestracji domen. Jeśli formularz płatności jest osadzony na Twojej stronie, czyli działa na Elements albo osadzonej wersji Checkout, Apple Pay, Google Pay i Link pokażą się dopiero po zarejestrowaniu w Stripe każdej domeny i subdomeny, na której stoi formularz, także wersji z www. Bez tego wpisu klient po prostu ich nie zobaczy.

Stripe, Przelewy24, PayU czy Tpay: kiedy który

Wybór zależy od tego, co sprzedajesz i komu. Za BLIK polscy operatorzy biorą według swoich cenników od 0,99% + 0,02 zł (Tpay Business z abonamentem) do 1,59% + 0,41 zł (Tpay Starter), a Stripe 1,6% + 1,00 zł. Stripe ma za to gotowy, choć osobno płatny moduł subskrypcji i rozliczenia w wielu walutach.

Stawki w tabeli pochodzą z publicznych cenników operatorów. Cenniki się zmieniają, a przy większym obrocie warunki i tak ustala się indywidualnie, więc to punkt wyjścia do rozmowy, nie oferta.

Policz najpierw swój średni koszyk. Płatność BLIKIEM za 60 zł kosztuje według tych cenników 1,07 zł w Przelewy24 (1,29% + 0,30 zł) i 1,96 zł w Stripe (1,6% + 1,00 zł). Różnica to 89 gr na każdym zamówieniu, blisko 1,5% jego wartości. Przy koszyku 3000 zł opłata stała przestaje mieć znaczenie, a liczy się stawka procentowa i to, czy karta pochodzi z EOG.

Nic nie stoi na przeszkodzie, żeby mieć dwóch operatorów: polskiego do sprzedaży krajowej i Stripe do subskrypcji albo klientów zagranicznych. Kosztem jest drugi zestaw webhooków, druga rekoncyliacja i dwa miejsca, w których trzeba szukać, gdy klient pisze, że zapłacił, a nic nie przyszło.

Stripe, Przelewy24, PayU i Tpay dla firmy w Polsce. Dane z publicznych cenników i dokumentacji operatorów.

Tabela jest szersza niż ekran: przesuń ją palcem w bok.

Webhooki, duplikaty i ponowienia

Klient zapłacił, przeglądarka się zawiesiła, a dostęp i tak ma się pojawić. Odpowiada za to webhook, czyli powiadomienie wysyłane przez operatora prosto na Twój serwer, i od jego obsługi zależy, czy integracja działa poprawnie także w takich sytuacjach.

Zasada pierwsza: potwierdzeniem płatności jest podpisane zdarzenie od operatora, nie powrót klienta pod adres z parametrem sukcesu. Taki adres da się wpisać ręcznie w pasku przeglądarki, a zdarzenia podpisanego sekretem, który zna tylko Twój serwer i operator, nie da się podrobić.

Zasada druga: zdarzenia przychodzą co najmniej raz, a nie dokładnie raz. Według dokumentacji Stripe niepotwierdzone zdarzenie jest w trybie produkcyjnym ponawiane przez maksymalnie trzy dni, z rosnącymi odstępami, a kolejność dostarczenia nie jest gwarantowana. Kod, który tego nie zakłada, wystawia dwie faktury i nadaje dwa dostępy.

Dlatego odbiornik zdarzeń buduję zawsze tak samo: sprawdzam podpis, zapisuję identyfikator zdarzenia, od razu odpowiadam kodem 2xx, a właściwą pracę wykonuję z kolejki, co zaleca też sam Stripe. Jego biblioteki domyślnie odrzucają zdarzenia z podpisem starszym niż pięć minut, co zamyka drogę do powtórzenia przechwyconego żądania.

Gdy kolejka się zatka albo zewnętrzna usługa zamilknie, zdarzenie nie może zniknąć. Zapisuję je z informacją o błędzie i ponawiam z rosnącym odstępem, a po serii nieudanych prób trafia tam, gdzie da się je obejrzeć i uruchomić ręcznie.

• Klucz idempotencjiZamówienie i dokument powstają pod własnym, powtarzalnym kluczem. Ponowione zdarzenie trafia na istniejący rekord i kończy się bez zmian.
• Weryfikacja podpisuŻądanie bez poprawnego podpisu jest odrzucane, zanim cokolwiek z niego przeczytam. Bez tego każdy, kto zna adres, zgłosi opłacone zamówienie.
• Brak założeń o kolejnościGdy brakuje wcześniejszego elementu układanki, dociągam aktualny stan z API operatora, zamiast odtwarzać go z kolejności powiadomień.
• Codzienna rekoncyliacjaRaz dziennie zestawiam płatności u operatora z zamówieniami i dokumentami. Rozjazd trafia do Ciebie w raporcie tego samego dnia, a nie przy zamknięciu miesiąca.

Bezpieczeństwo, dane kart i PCI DSS

Zasada, której się trzymam: numer karty nie przechodzi przez Twój serwer ani przez kod, który piszę. Na niej opiera się cała architektura integracji płatności, a obowiązki PCI DSS opisuję niżej.

Stripe Checkout i Elements zbierają numer karty w ramce serwowanej z domeny Stripe, nie z Twojej, a Payment Links otwierają stronę płatności hostowaną przez Stripe. Według przewodnika PCI na stripe.com taka integracja kwalifikuje się do SAQ A, czyli najkrótszego formularza samooceny PCI DSS.

SAQ A nie oznacza, że nie trzeba robić nic. Zgodność potwierdza się co roku, strona płatności musi działać po TLS w wersji 1.2 lub nowszej, a według tego samego przewodnika firmy z poziomów 2–⁠4 wykonują też kwartalny skan sieci u zatwierdzonego dostawcy (ASV).

Reszta to higiena, która z PCI nie ma wiele wspólnego, a i tak decyduje o bezpieczeństwie. Klucz tajny żyje wyłącznie po stronie serwera i nigdy nie trafia do repozytorium. Dostęp do panelu operatora dostaje imienne konto z drugim składnikiem logowania, nie wspólne hasło zespołu.

Do tego dochodzi polityka bezpieczeństwa treści. Formularz płatności wymaga wpuszczenia konkretnych adresów w dyrektywach script-src, frame-src i connect-src. Zbyt szeroka reguła osłabia stronę, zbyt wąska po cichu blokuje płatność, zwykle dopiero na produkcji.

Jak wygląda wdrożenie i testy przed uruchomieniem

Integrację buduję na kluczach testowych operatora i dopiero na końcu przełączam ją na produkcyjne. Wcześniej przechodzimy przez listę sytuacji, które w prawdziwym ruchu zdarzają się w pierwszym tygodniu.

Ustalamy też, kto ma dostęp do czego: konto operatora, program fakturowy, CRM i hosting. Integracja utrzymywana przez jedną osobę z kompletem haseł jest ryzykiem biznesowym, nie technicznym.

1. Mapa zdarzeńRozpisujemy, co ma się stać po płatności, po zwrocie, po płatności odrzuconej i po anulowaniu subskrypcji. Ten dokument jest jednocześnie listą testów.
2. Klucze i środowiskaOsobne klucze testowe i produkcyjne, osobne adresy webhooków, osobne konto w programie fakturowym i testowe środowisko e-faktur. Dane testowe nie mogą wejść do numeracji prawdziwych dokumentów.
3. Przebieg podstawowyPłatność kartą, BLIKIEM i przelewem, każda doprowadzona do końca: zamówienie, dokument, wpis w CRM, wiadomość do klienta. Sprawdzam to także na telefonie.
4. Sytuacje trudneKarta przeglądarki zamknięta przed powrotem ze strony banku, płatność odrzucona, dwukrotne kliknięcie, zdarzenie doręczone dwa razy, zwrot częściowy, usługa zewnętrzna bez odpowiedzi.
5. Przełączenie i próba na żywoPo zmianie kluczy robimy jedną prawdziwą transakcję na małą kwotę i zwracamy ją, żeby sprawdzić cały obieg razem z dokumentem korygującym.

Co monitoruję po starcie

Integracja nie kończy się w dniu uruchomienia. Zmieniają się wersje API, wygasają certyfikaty, operator dokłada wymagania, a zewnętrzna usługa miewa gorszy dzień.

• Nieudane dostarczenia zdarzeńPanel operatora pokazuje zdarzenia z błędem i zaplanowane ponowienia. Seria odpowiedzi 5xx to pierwszy sygnał, że coś po Twojej stronie zwalnia.
• Rekordy zatrzymane w kolejceZdarzenie nieprzetworzone za trzecim razem musi być widoczne razem z kwotą i klientem. Inaczej dowiesz się o nim z wiadomości od kupującego.
• Zgodność liczbDzienne zestawienie płatności u operatora z zamówieniami i wystawionymi dokumentami. Interesuje mnie każda różnica, także ta na jedną transakcję.
• Statusy wysyłki do KSeFFaktura odrzucona przez system to faktura, której nie ma. Status i numer sprawdzam razem z resztą zestawienia, a nie raz na kwartał.
• Zmiany po stronie usługWycofywane wersje API, nowe wymagania operatora, wygasające klucze i certyfikaty. Zmianę ogłoszoną z wyprzedzeniem wdrażam w spokojnym terminie; zauważona dopiero po awarii oznacza zatrzymaną sprzedaż.
• Opieka po wdrożeniu: 300–⁠900 zł netto miesięcznieMonitoring, reakcja na zmianę API po stronie dostawcy i pula godzin na poprawki mogą być stałą usługą zamiast doraźnych zleceń. Kontakt bezpośrednio do mnie, bez systemu zgłoszeń; opieka nie jest obowiązkowa. Co wchodzi w zakres i od czego zależy kwota.