Przelewy24 API: integracja i automatyzacja bez ręcznego sprawdzania, kto zapłacił
Warstwa techniczna płatności: rejestracja transakcji, przekierowanie kupującego, powiadomienie o statusie przychodzące na Wasz adres i weryfikacja podpisu, zanim cokolwiek uznamy za zapłacone. Do tego idempotencja przy podwójnych powiadomieniach, uzgadnianie wpłaty z zamówieniem i z fakturą oraz zwroty. Testy idą w środowisku testowym Przelewy24, na osobnych kluczach, nie na Waszej produkcji.
- 1 źródło prawdyo statusie płatności decyduje zweryfikowane powiadomienie od operatora, a nie to, że kupujący wrócił na stronę z podziękowaniem
- 0 danych kartowychnumeru karty i kodu CVV nie przechowujemy i nie przetwarzamy; kupujący podaje je po stronie operatora płatności
- 2 do 4 tygodniod warsztatu do działającej integracji, po przejściu scenariuszy brzegowych w środowisku testowym
- 14 dnityle zwykle mija od warsztatu do pierwszej działającej automatyzacji, najczęściej faktury wystawianej po uznanej wpłacie
Problem
Dlaczego zamówienie bywa opłacone, a w systemie nieopłacone?
Klient płaci BLIK-iem, dostaje potwierdzenie z banku i zamyka kartę przeglądarki, zanim wróci na Waszą stronę. W panelu zamówienie wisi jako nieopłacone, więc rano ktoś porównuje wyciąg z listą zamówień i dopisuje wpłaty ręcznie. Wieczorem ten sam ktoś wystawia faktury do wpłat, które doszły w ciągu dnia.
Druga wersja tego samego problemu jest odwrotna. Powiadomienie o płatności przychodzi dwa razy, bo pierwsza odpowiedź Waszego serwera nie doszła w czasie, i klient dostaje dwie faktury oraz dwa maile z dostępem. Trzecia wersja jest najgorsza: ktoś wysyła na Wasz adres żądanie, które wygląda jak potwierdzenie zapłaty, a integracja bierze je na wiarę i zamyka zamówienie.
Kolejność kroków nie jest tu kwestią gustu. Dokumentacja Przelewy24 dla programistów opisuje to jako dwa osobne kroki: najpierw powiadomienie o statusie na adres podany w panelu, potem weryfikacja transakcji zapytaniem do operatora, z podpisem liczonym z pól transakcji i tajnego klucza CRC. Integracja, która robi tylko pierwszy krok, uznaje za płatność każde żądanie, jakie ktokolwiek wyśle na Wasz adres.
- Klient zapłacił, a zamówienie czeka, bo nikt nie dopisał wpłaty
- Ktoś codziennie porównuje wyciąg z listą zamówień i szuka różnic
- Podwójne powiadomienie tworzy drugą fakturę i drugi mail do klienta
- Zwrot wpisany w panelu operatora nie ma odbicia w zamówieniu ani w korekcie faktury
- Nikt nie potrafi powiedzieć, na jakiej podstawie zamówienie zostało uznane za opłacone
Dlaczego teraz
Co się zmieniło, że płatności da się spiąć w tygodnie, nie w kwartał?
Bramka płatnicza ma dziś interfejs do wszystkiego, co wcześniej robiło się w panelu: rejestracji transakcji, sprawdzenia statusu, zwrotu, pobrania listy operacji. Nie trzeba czekać na wyciąg ani na eksport CSV, żeby wiedzieć, kto zapłacił.
Druga zmiana jest po stronie warstwy automatyzacji. n8n, Make albo własna integracja przez API dają kolejkę, ponawianie i log, więc powiadomienie nie ginie, gdy Wasz serwer był akurat w restarcie. Weryfikacja podpisu i klucz idempotencji nadal muszą tam być, bo żadne narzędzie nie zrobi ich za Was; różnica jest w tym, że nie trzeba pisać pod to całego backendu.
Trzecia zmiana to agent AI. Integracja dopisze wpłatę do zamówienia, ale nie odpowie księgowej na pytanie „które wczorajsze wpłaty nie mają jeszcze faktury”. BOND, nasz firmowy agent AI, odpowiada na to z danych firmy w 5 do 10 sekund, bez logowania do panelu płatności.
Co się zmienia
Co dostaje zespół, który dziś ręcznie sprawdza wpłaty?
Status płatności bez pytania klienta o potwierdzenie
Powiadomienie z bramki trafia na Wasz adres w sekundy po zapłacie, integracja potwierdza je zapytaniem do operatora i dopisuje wpłatę do zamówienia. Zamknięta przeglądarka klienta przestaje mieć znaczenie.
Źródłem prawdy jest zweryfikowane powiadomienie, nie powrót kupującego na stronę
Fałszywe potwierdzenie nie przechodzi
Zanim cokolwiek uznamy za zapłacone, sprawdzamy podpis powiadomienia kluczem CRC z Waszego panelu, a kwotę i walutę porównujemy z zamówieniem. Żądanie bez poprawnego podpisu ląduje w logu, nie w zamówieniach.
Podpis, kwota i waluta sprawdzane przed uznaniem wpłaty, każde odrzucenie zapisane
Podwójne powiadomienie nie robi drugiej faktury
Każda płatność ma klucz wyliczony z identyfikatora sesji, więc drugie i trzecie powiadomienie o tej samej transakcji kończy się bez skutku. Klient nie dostaje dwóch faktur ani dwóch maili z dostępem.
Klucz idempotencji z identyfikatora sesji płatności, powtórka kwitowana i pomijana
Faktura w kilka sekund po uznaniu wpłaty
Po pozytywnej weryfikacji integracja zakłada fakturę w Fakturowni, iFirmie albo Comarch Optima, wysyła ją kupującemu i przesuwa zamówienie w sklepie i w CRM. Nie po przekierowaniu, tylko po potwierdzonej płatności.
Faktura wystawiana po weryfikacji transakcji, nie po samym przekierowaniu kupującego
Wpłaty bez powiadomienia widać tego samego dnia
Codzienne uzgodnienie porównuje operacje z bramki z zamówieniami i fakturami, a różnice wypisuje z powodem. Wpłata, o której powiadomienie nigdy nie doszło, wychodzi z listy, a nie z telefonu od klienta.
Trzy rodzaje rozjazdu: wpłata bez zamówienia, zamówienie bez wpłaty, kwota inna niż zamówiona
Zwroty i dopłaty z jednego miejsca
Zwrot całości albo części kwoty uruchamiasz z poziomu zamówienia, a integracja rejestruje go w bramce i podnosi korektę faktury. Obsługa nie loguje się do panelu płatności, żeby oddać 40 zł za jedną pozycję.
Zwrot częściowy zapisany przy zamówieniu i w korekcie, z tym samym identyfikatorem transakcji
A u Ciebie
Co, jeśli mamy już wtyczkę płatności w sklepie?
Cztery zdania, które słyszymy najczęściej przy płatnościach, i to, co na nie odpowiadamy.
Mamy wtyczkę Przelewy24 w WooCommerce, po co coś więcej?
Jeśli sprzedajecie jednym sklepem, a faktury wystawiacie z niego, wtyczka wystarcza i tak Wam powiemy na konsultacji. Integracja przez API ma sens wtedy, gdy jedna wpłata ma pociągnąć fakturę w osobnym programie, etap w CRM, dostęp do produktu i rezerwację na magazynie, albo gdy sprzedaż idzie kilkoma kanałami naraz.
Nie chcemy dotykać płatności na produkcji.
I nie dotykamy. Przepływ powstaje na osobnych kluczach w środowisku testowym Przelewy24, potem chodzi w trybie obserwacji obok obecnej ścieżki i tylko zapisuje, co by zrobił. Przełączamy dopiero wtedy, gdy jego decyzje zgadzają się z tym, co widzicie w panelu.
Czy będziecie mieli dostęp do danych kart naszych klientów?
Nie. Numer karty i kod CVV kupujący podaje na stronie operatora płatności, a przez Wasz serwer i przez workflow przechodzą tylko identyfikator sesji, kwota, waluta, status i dane potrzebne do faktury. Dzięki temu zakres wymagań PCI DSS po Waszej stronie zostaje wąski, a my nie przechowujemy ani nie przetwarzamy danych kartowych.
Sprzedajemy w kilku walutach i przez marketplace.
Wtedy źródeł prawdy o pieniądzach jest więcej niż jedno: bramka płatnicza dla sprzedaży z Waszego sklepu, rozliczenia platformy dla sprzedaży z marketplace. Na warsztacie ustalamy, co uzgadniamy z czym i w jakiej walucie zapisujemy zamówienie, żeby ta sama wpłata nie została policzona dwa razy.
- Płatności
- Przelewy24, środowisko testowe i osobne klucze dla każdego środowiska
- Sklepy i sprzedaż
- Shopify, WooCommerce, PrestaShop, BaseLinker, Allegro
- Fakturowanie i księgowość
- Fakturownia, iFirma, Comarch Optima, Subiekt, sevDesk
- CRM
- HubSpot, Pipedrive, Salesforce, LiveSpace
- Powiadomienia i praca zespołu
- Slack, Microsoft Teams, Google Workspace, Microsoft 365
- Dane i warstwa automatyzacji
- BigQuery, Google Sheets, n8n, Make, własne integracje przez API
Sytuacje w płatnościach i co z nimi robi integracja
Płatności są proste w wariancie, w którym wszystko idzie dobrze. Pracę generują wiersze poniżej, dlatego spisujemy je na warsztacie, zanim ktokolwiek napisze pierwszy węzeł przepływu.
| Sytuacja | Co robi integracja | Czego nie robi |
|---|---|---|
| Powiadomienie o zapłacie | sprawdza podpis, potwierdza status zapytaniem do operatora, dopisuje wpłatę do zamówienia | nie uznaje płatności na podstawie samego żądania na adres webhooka |
| Kupujący wrócił na stronę, powiadomienia nie ma | trzyma zamówienie w stanie „płatność w toku” i czeka na potwierdzenie | nie wystawia faktury i nie wysyła dostępu do produktu |
| To samo powiadomienie przyszło dwa razy | rozpoznaje je po identyfikatorze sesji i kończy bez skutku | nie tworzy drugiej faktury ani drugiego maila z dostępem |
| Kwota inna niż w zamówieniu | zapisuje wpłatę i wystawia rozjazd do decyzji człowieka | nie zamyka zamówienia po cichu i nie dopłaca różnicy |
| Wpłata, o której powiadomienie nie doszło | wyłapuje ją przy dziennym uzgodnieniu i podnosi zgłoszenie z powodem | nie czeka na telefon od klienta, który zapłacił |
| Zwrot całości albo części kwoty | rejestruje zwrot przy zamówieniu i uruchamia korektę faktury | nie zwraca środków bez potwierdzenia po Waszej stronie |
| Dane karty kupującego | przetwarza identyfikator sesji, kwotę, walutę i status transakcji | nie przechowuje numeru karty ani kodu CVV |
Wiersze to punkt wyjścia. Które z tych sytuacji są u Was realne, wychodzi na warsztacie: przy produktach cyfrowych najwięcej waży wiersz o dostępie do produktu, przy sprzedaży fizycznej wiersz o zwrotach częściowych.
Jak to robimy
Pięć kroków od ręcznego dopisywania wpłat do integracji na produkcji
Każdy krok kończy się czymś, co możesz ocenić, zanim zdecydujesz o następnym. Do przełączenia nic nie rusza Waszej produkcyjnej ścieżki płatności.
Warsztat
Rozkładamy dzisiejszą drogę pieniędzy: od kliknięcia „Zapłać” do faktury i do wpisu w księgowości. Kto uznaje wpłatę i na jakiej podstawie, kto szuka brakujących, ile to zajmuje w tygodniu. Spisujemy sytuacje brzegowe z tabeli powyżej, bo w płatnościach właśnie one kosztują czas.
Projekt przepływu
Ustalamy kolejność i źródło prawdy: rejestracja transakcji, przekierowanie kupującego, powiadomienie na Wasz adres, weryfikacja transakcji u operatora, dopiero potem faktura i dostęp do produktu. Do tego sposób liczenia podpisu, klucz idempotencji, kolejka na wypadek niedostępności Waszego systemu i zasada, kiedy sprawa idzie do człowieka.
Środowisko testowe
Przepływ powstaje na osobnych kluczach w środowisku testowym Przelewy24, z testowymi metodami płatności z dokumentacji. Przechodzimy scenariusze, których nikt nie chce przechodzić na produkcji: powiadomienie z podmienioną kwotą, to samo powiadomienie dwa razy, brak powiadomienia, zwrot częściowy, płatność po anulowaniu zamówienia.
Tryb obserwacji i przełączenie
Integracja chodzi obok obecnej ścieżki i tylko zapisuje, co by zrobiła. Porównujemy jej decyzje ze stanem w panelu i przełączamy, gdy statusy się zgadzają. Monitoring i alert o powiadomieniu, którego nie udało się przetworzyć, wchodzą razem z przełączeniem, a nie po pierwszej awarii.
Uzgadnianie i pomiar
Dzienne uzgodnienie zestawia operacje z bramki z zamówieniami i z fakturami, a różnice wypisuje z powodem. Po 30 i po 90 dniach patrzymy na jedną liczbę: ile wpłat wymagało ręki człowieka i dlaczego. Ta liczba mówi, czy integracja działa, a nie to, że nikt się nie skarżył.
Przed i po
Jak zmienia się dzień osoby, która pilnuje wpłat
Przedtem
- Rano porównuje wyciąg z listą zamówień i dopisuje brakujące wpłaty
- Odbiera telefon od klienta, który zapłacił, a zamówienie stoi
- Zwrot robi w panelu operatora, korektę faktury osobno, z pamięci
- Faktury do dziennych wpłat wystawia wieczorem, kiedy ma na to czas
Po zmianie
- Wpłata dopisuje się do zamówienia w kilka sekund po zweryfikowanym powiadomieniu
- Rozjazdy dostaje z listy, z powodem, zanim klient zdąży zadzwonić
- Zwrot uruchamia z zamówienia, korekta faktury idzie w tym samym przebiegu
- Faktura i dostęp do produktu wychodzą do klienta bez udziału człowieka
Pierwsze zweryfikowane płatności widać w dniu przełączenia. Liczbę wpłat wymagających ręcznego uzgodnienia oceniamy po 30 i po 90 dniach, na Waszych danych.
Dla osoby, która to zamawia
Co z tego ma właściciel sprzedaży online
Pytanie „czy ten klient zapłacił” przestaje wracać do ludzi. Status wpłaty ma jedno źródło i datę, a każde uznanie płatności zostawia w logu podstawę: identyfikator sesji, kwotę, walutę, wynik weryfikacji podpisu. Przy sporze z klientem albo przy kontroli pokazujesz zapis, nie pamięć pracownika.
Druga rzecz waży więcej w rozmowie z księgowością i z zarządem. Wiesz, ile wpłat w miesiącu wymagało ręcznego uzgodnienia i z jakiego powodu. To liczba, którą da się zmniejszać, i podstawa do policzenia, ile realnie kosztuje obsługa jednej transakcji.
- Każde uznanie płatności ma w logu podstawę: sesja, kwota, waluta, podpis
- Numeru karty i kodu CVV nie ma w Waszych systemach ani w naszym workflow
- Rozjazdy przychodzą z listy, nie od klienta, który zapłacił i czeka
- Do przełączenia nowa ścieżka tylko obserwuje, stara obsługuje płatności
Ile to kosztuje
Warsztat ma cenę jawną, wdrożenie wycenę po nim
Warsztat procesowy kosztuje 2500 zł netto za tydzień. Przy płatnościach zwykle wystarcza jeden tydzień, dwa wtedy, gdy w grę wchodzi kilka kanałów sprzedaży albo kilka walut. Wdrożenie wyceniamy po warsztacie, bo zakres zależy od tego, ile systemów ma zobaczyć jedną wpłatę: sklep, magazyn, CRM, program do faktur.
Prowizję od transakcji płacisz operatorowi płatności, a koszt narzędzia automatyzacji jego dostawcy albo nie płacisz go wcale, gdy warstwa stoi na Waszej infrastrukturze. Bez naszej prowizji od jednego i od drugiego.
Warsztat procesowy
2500 zł netto
za tydzień, przy płatnościach zwykle jeden do dwóch
Zamknięta całość. Kończy się opisem ścieżki płatności i zasadami uznawania wpłaty, które obronią się bez nas.
- Mapa drogi pieniędzy od kliknięcia „Zapłać” do wpisu w księgowości
- Lista sytuacji brzegowych z decyzją, co robimy w każdej z nich
- Rekomendacja: wtyczka w sklepie, warstwa automatyzacji albo integracja przez API
- Zasady uznawania płatności i wskaźniki do pomiaru po 30 dniach
- Najczęściej wybierany
Warsztat i wdrożenie integracji
Wycena po warsztacie
zakres wynika z liczby systemów, które mają zobaczyć wpłatę
Najczęściej wybierany wariant. Działająca integracja w 2 do 4 tygodni od warsztatu, przełączana po trybie obserwacji.
- Wszystko z warsztatu
- Rejestracja transakcji i obsługa powiadomień z weryfikacją podpisu
- Idempotencja, kolejka i ponawianie, żeby powiadomienie nie zginęło
- Uzgadnianie wpłat z zamówieniami i fakturami, dzienny raport rozjazdów
- Środowisko testowe, osobne klucze, tryb obserwacji i przełączenie z monitoringiem
Płatności i agent AI
Wycena po warsztacie
dla zespołów, które pytają o wpłaty kilka razy dziennie
Wszystko z wdrożenia plus BOND, który odpowiada na pytania o wpłaty i faktury zwykłym zdaniem.
- Wszystko z wdrożenia integracji
- Agent AI spięty z zamówieniami, płatnościami i programem do faktur
- Alerty o wpłacie bez zamówienia i o zamówieniu bez wpłaty
- Odpowiedzi w 5 do 10 sekund, bez logowania do panelu płatności
Warsztat kończy się dokumentem, który obroni się bez nas: ścieżka płatności, lista sytuacji brzegowych, zasady uznawania wpłaty. Jeśli wyjdzie z niego, że wtyczka w Waszym sklepie robi już to, co potrzebne, mówimy to i pokazujemy, co poprawić w konfiguracji. Przy płatnościach nie obiecujemy, że nigdy nic się nie rozjedzie. Obiecujemy, że rozjazd będzie widoczny tego samego dnia i będzie miał właściciela.
Najczęstsze pytania
Czym jest integracja Przelewy24 przez API?
To spięcie bramki płatniczej z Waszymi systemami bez logowania do panelu. Wasz sklep albo backend rejestruje transakcję i przekierowuje kupującego do wyboru metody płatności, a po zapłacie na wskazany adres przychodzi powiadomienie o statusie. Integracja weryfikuje je u operatora i dopiero wtedy uruchamia to, co ma się stać po płatności: fakturę, dostęp do produktu, zmianę etapu w CRM.
Dlaczego powiadomienie o statusie jest ważniejsze niż powrót klienta na stronę?
Bo powrót przeglądarki zależy od kupującego, a powiadomienie od operatora. Klient może zamknąć kartę, stracić zasięg albo zapłacić w aplikacji banku na telefonie i nigdy nie wrócić na stronę z podziękowaniem. Powiadomienie przychodzi wtedy tak samo, dlatego to ono jest źródłem prawdy o statusie, potwierdzone osobnym zapytaniem do operatora.
Po co weryfikować podpis powiadomienia?
Bo adres, na który przychodzą powiadomienia, jest publiczny. Bez sprawdzenia podpisu każdy, kto go zgadnie, mógłby wysłać fałszywe potwierdzenie zapłaty i zamknąć zamówienie bez pieniędzy. Podpis liczymy z pól transakcji i tajnego klucza CRC z Waszego panelu, według dokumentacji Przelewy24, a dodatkowo porównujemy kwotę i walutę z zamówieniem.
Co się dzieje, gdy klient zapłacił, a powiadomienie nie doszło?
Nieodebrane powiadomienie wraca, bo operator ponawia wysyłkę, gdy Wasz endpoint nie odpowie poprawnie. Po naszej stronie stoi kolejka, więc przetworzenie odkłada się na później, zamiast przepadać. Wpłatę, o której powiadomienie nie doszło w ogóle, wyłapuje dzienne uzgodnienie z operacjami z bramki i podnosi ją jako rozjazd z powodem, do decyzji człowieka.
Jak radzicie sobie z podwójnymi powiadomieniami?
Każda płatność ma klucz wyliczony z identyfikatora sesji. Pierwsze powiadomienie uruchamia skutki, drugie i trzecie zostają zakwitowane i pominięte. Dzięki temu klient nie dostaje dwóch faktur, dwóch maili z dostępem ani dwóch rezerwacji na magazynie, nawet jeśli operator wyśle to samo zdarzenie kilka razy.
Czy testujecie na prawdziwych płatnościach?
Nie. Przepływ powstaje w środowisku testowym Przelewy24, na osobnych kluczach, z testowymi metodami płatności z dokumentacji. Potem chodzi w trybie obserwacji obok obecnej ścieżki i tylko zapisuje, co by zrobił. Na produkcję przełączamy, gdy jego decyzje zgadzają się z tym, co widzicie w panelu.
Czy przechowujecie dane kart naszych klientów?
Nie. Numer karty i kod CVV kupujący podaje na stronie operatora płatności, więc nie przechodzą ani przez Wasz serwer, ani przez nasz workflow. Przetwarzamy identyfikator sesji, kwotę, walutę, status i dane potrzebne do faktury. To trzyma zakres wymagań PCI DSS po Waszej stronie wąsko i o tym też mówimy na warsztacie.
Jak wygląda automatyczna faktura po wpłacie i zwrot?
Po pozytywnej weryfikacji integracja zakłada fakturę w Fakturowni, iFirmie albo Comarch Optima z danymi z zamówienia i wysyła ją kupującemu. Zwrot całości albo części kwoty uruchamiasz z poziomu zamówienia: integracja rejestruje go w bramce i podnosi korektę faktury z tym samym identyfikatorem transakcji. Sam przelew zwrotny nigdy nie idzie bez potwierdzenia po Waszej stronie.
Sprawdźmy, gdzie dziś rozjeżdżają się Wasze wpłaty
Bezpłatna konsultacja trwa 30 minut. Opowiadasz, jak wygląda droga od kliknięcia „Zapłać” do faktury i kto sprawdza, czy wpłata doszła. Pokazujemy, co da się spiąć od razu, a co wymaga najpierw uporządkowania zamówień albo fakturowania. Nie musisz na tym etapie dawać nam dostępu do panelu płatności ani do kluczy.
Prowadzimy najwyżej dwa wdrożenia równocześnie, żeby przy każdym ktoś realnie siedział.
Umów bezpłatną konsultacjęPS. Jeśli w tym tygodniu ktoś u Was ręcznie sprawdzał, czy klient zapłacił, to jest dokładnie ten problem. Zweryfikowane powiadomienie o statusie zdejmuje to z człowieka i zostawia zapis, którym obronisz każdą uznaną płatność. Od tego zaczyna się warsztat, a pierwsza automatyzacja rusza zwykle 14 dni po nim.