Jak działa integracja z PayU?

Sama integracja nie sprowadza się do dodania przycisku „Zapłać”. Najważniejsze jest poprawne tworzenie transakcji, odbieranie powiadomień z PayU i właściwa reakcja systemu na każdy status płatności.

Czym jest integracja z PayU?

Integracja z PayU oznacza techniczne połączenie własnego systemu – np. sklepu internetowego, platformy SaaS, serwisu rezerwacyjnego czy systemu sprzedażowego – z systemem płatniczym PayU.

Dzięki temu użytkownik nie musi wykonywać tradycyjnego przelewu i przepisywać numeru rachunku, kwoty czy tytułu płatności. System może sam utworzyć transakcję z odpowiednią kwotą i przypisać ją do konkretnego zamówienia, faktury lub klienta.

W podstawowym wariancie klient wybiera opcję płatności PayU, zostaje przekierowany na stronę płatniczą, dokonuje płatności, a następnie wraca do serwisu sprzedawcy. Równolegle PayU komunikuje się bezpośrednio z systemem sprzedawcy i przekazuje mu aktualny status transakcji.

To ostatnie jest szczególnie ważne. Sam fakt, że klient wrócił na stronę po dokonaniu płatności, nie powinien być podstawą do uznania zamówienia za opłacone.

Jak działa integracja z PayU krok po kroku?

W typowej integracji można wyróżnić kilka etapów.

Przyjrzyjmy się temu dokładniej.

1. Klient wybiera PayU

Proces rozpoczyna się najczęściej po kliknięciu przycisku:

„Zapłać”,
„Zapłać online”,
„Przejdź do płatności”
lub podobnego.

Może to nastąpić bezpośrednio podczas składania zamówienia albo później – np. poprzez link do płatności umieszczony przy fakturze.

System powinien już wtedy wiedzieć:

2. System uwierzytelnia się w PayU

Aplikacja nie może anonimowo wysyłać do PayU żądań dotyczących płatności.

W standardowej integracji REST API wykorzystywane jest uwierzytelnienie OAuth. System korzysta m.in. z danych client_id oraz client_secret powiązanych z odpowiednim punktem płatności POS i pobiera token służący do autoryzacji kolejnych żądań.

Dane dostępowe powinny znajdować się po stronie serwera.

Nie należy umieszczać kluczy prywatnych bezpośrednio w kodzie JavaScript wykonywanym w przeglądarce użytkownika.

3. Tworzone jest zamówienie w PayU

Następnie system wysyła do PayU żądanie utworzenia transakcji.

W aktualnym REST API standardowe utworzenie zamówienia odbywa się poprzez endpoint /api/v2_1/orders.

Do PayU mogą zostać przekazane między innymi:

To właśnie powiązanie własnego identyfikatora zamówienia z identyfikatorem PayU pozwala później jednoznacznie ustalić, której transakcji dotyczy otrzymana płatność.

4. Klient zostaje przekierowany do płatności

Jeżeli transakcja została utworzona prawidłowo, system otrzymuje odpowiedź umożliwiającą skierowanie klienta do procesu płatności.

Klient wybiera następnie jedną z dostępnych dla niego metod.

PayU obsługuje różne formy płatności, których dostępność zależy m.in. od rynku, konfiguracji punktu płatności i zawartej umowy. W Polsce szczególnie istotne są płatności bankowe, karty oraz BLIK; w ekosystemie PayU dostępne są również portfele cyfrowe, takie jak Apple Pay czy Google Pay.

Jak wygląda płatność BLIK?

W jednym z podstawowych wariantów klient wybiera BLIK, podaje kod wygenerowany w aplikacji bankowej i zatwierdza transakcję na telefonie.

PayU przewiduje również bardziej zaawansowane warianty integracji BLIK, w tym płatność z kodem autoryzacyjnym oraz rozwiązania wykorzystujące token UID do płatności one-click.

Dla zwykłego użytkownika techniczne różnice nie muszą być widoczne. Ma on po prostu szybko dokonać płatności.

5. PayU przetwarza transakcję

Po wykonaniu płatności rozpoczyna się najważniejszy etap z punktu widzenia systemu sprzedawcy.

Nie każda transakcja kończy się natychmiast sukcesem. Płatność może być jeszcze przetwarzana, oczekiwać na dodatkowe działanie, zostać zakończona albo anulowana.

W PayU podstawowe statusy zamówienia to:

Z biznesowego punktu widzenia szczególne znaczenie ma status COMPLETED.

Dopiero po uzyskaniu wiarygodnej informacji o zakończeniu płatności system powinien wykonywać operacje przeznaczone dla opłaconego zamówienia.

Może to być np.:

6. PayU wysyła powiadomienie do systemu

To jeden z najważniejszych elementów całej integracji.

PayU może wysyłać do określonego adresu systemu sprzedawcy powiadomienia o zmianach statusu transakcji. Są one często nazywane webhookami lub notyfikacjami.

Adres do odbioru takich informacji przekazywany jest podczas tworzenia zamówienia jako notifyUrl.

Przykładowo:

klient płaci → bank potwierdza płatność → PayU aktualizuje transakcję → PayU wysyła powiadomienie → sklep oznacza zamówienie jako opłacone.

Dlaczego webhook jest ważniejszy niż powrót klienta na stronę?

Wyobraźmy sobie następującą sytuację.

Klient dokonuje płatności BLIK. Transakcja zostaje zaakceptowana, ale tuż później:

Jeżeli system uzależnia oznaczenie zamówienia jako opłaconego wyłącznie od powrotu użytkownika na stronę, może nigdy nie zarejestrować prawidłowo płatności.

Dlatego logika biznesowa powinna opierać się przede wszystkim na komunikacji serwer-serwer.

Dokumentacja PayU wskazuje, że status zamówienia powinien być ustalany na podstawie notyfikacji, a system odbierający powiadomienie powinien prawidłowo je przetworzyć i odpowiedzieć kodem HTTP 200.

7. Klient wraca na stronę sklepu lub aplikacji

Oprócz notifyUrl w integracji występuje również adres powrotu użytkownika – continueUrl.

Po przejściu procesu płatności klient może zostać skierowany np. na stronę:

„Dziękujemy. Twoja płatność została przyjęta.”

Nie oznacza to jednak, że sama wizyta na tej stronie jest potwierdzeniem otrzymania pieniędzy.

Adres powrotu służy przede wszystkim do zapewnienia prawidłowego doświadczenia użytkownika, natomiast status transakcji powinien być ustalany niezależnie.

Jak integracja z PayU może działać przy fakturach?

Integracja z bramką płatniczą nie musi dotyczyć wyłącznie sklepów internetowych.

Można ją wykorzystać także w systemie fakturowym.

Przykład:

W takim modelu znika część pracy związanej z ręcznym sprawdzaniem rachunku bankowego i wyszukiwaniem odpowiednich przelewów.

PayU a automatyczne rozliczanie płatności

Największa wartość integracji pojawia się wtedy, kiedy bramka płatnicza zostaje połączona z pozostałymi procesami firmy.

Samo umożliwienie zapłaty online jest wygodne.

Automatyzacja rozpoczynająca się po płatności może być jednak znacznie cenniejsza.

Po otrzymaniu potwierdzenia system może automatycznie:

W praktyce powstaje jeden ciąg:

zamówienie → płatność → potwierdzenie → realizacja → rozliczenie.

Im mniej ręcznych czynności znajduje się pomiędzy tymi etapami, tym łatwiejsza jest obsługa większej liczby transakcji.

Czy klient musi mieć konto w PayU?

Z punktu widzenia typowego procesu sprzedażowego klient nie musi zakładać specjalnego konta w serwisie PayU tylko po to, aby dokonać standardowej płatności.

Wybiera dostępną metodę i przechodzi właściwy dla niej proces autoryzacji.

W przypadku BLIK będzie to najczęściej potwierdzenie w aplikacji bankowej, przy karcie – odpowiednia autoryzacja karty, a przy płatnościach bankowych – przejście przez system banku.

Jak wyglądają zwroty środków?

Dobra integracja powinna uwzględniać nie tylko przyjmowanie pieniędzy, ale również ich zwracanie.

PayU pozwala wykonywać zwroty pełne oraz częściowe. Zwrot może zostać zlecony przez API, a w określonych przypadkach również z panelu menedżerskiego.

Przykład:

Klient kupił trzy produkty za łącznie 450 zł, ale jeden produkt o wartości 100 zł został zwrócony.

Nie trzeba zwracać całej transakcji. Możliwy może być zwrot częściowy obejmujący wyłącznie odpowiednią kwotę.

Po przetworzeniu zwrotu PayU może również przekazać do systemu powiadomienie o jego statusie.

Dzięki temu aplikacja może automatycznie zapisać informację:

płatność: 450 zł, zwrot: 100 zł, pozostaje rozliczone: 350 zł.

Co się stanie, jeżeli klient nie dokończy płatności?

To normalny przypadek, który trzeba uwzględnić przy projektowaniu integracji.

Klient może:

Dlatego utworzenie transakcji w PayU nie jest równoznaczne z zapłatą.

System musi rozróżniać przynajmniej:

transakcję utworzoną
od
transakcji skutecznie zakończonej.

To jeden z najczęstszych błędów występujących w źle przygotowanych integracjach.

Co w przypadku opóźnienia powiadomienia?

System powinien być przygotowany również na problemy komunikacyjne.

PayU ponawia wysyłanie nieodebranych powiadomień według określonego harmonogramu. Dokumentacja opisuje serię kolejnych prób, jeżeli wcześniejsze powiadomienie nie zostało prawidłowo odebrane.

Dlatego endpoint odbierający webhook powinien:

Uwaga na Cloudflare i firewall

Ciekawym, praktycznym problemem może być blokowanie komunikacji przez zabezpieczenia serwera.

W dokumentacji PayU wskazano przykładowo sytuację, w której Cloudflare może blokować przychodzące notyfikacje na podstawie adresu IP albo nagłówka User-Agent. Efektem może być brak aktualizacji statusu w sklepie mimo udanej płatności.

Jeżeli więc klient zapłacił, PayU pokazuje transakcję jako zakończoną, ale sklep cały czas pokazuje „oczekuje na płatność”, jednym z pierwszych elementów do sprawdzenia powinien być mechanizm odbierania notyfikacji.

Jak bezpiecznie zintegrować PayU?

Integracja płatności dotyczy pieniędzy, dlatego nie warto traktować jej tak samo jak zwykłego połączenia dwóch niezależnych aplikacji.

1. Klucze przechowuj po stronie serwera

Dane dostępowe do API nie powinny trafiać do publicznego kodu strony.

2. Nie ufaj informacjom przesyłanym przez przeglądarkę

Użytkownik nie powinien mieć możliwości samodzielnego przesłania informacji:

„zamówienie zostało zapłacone”.

Status powinien pochodzić z wiarygodnego źródła.

3. Sprawdzaj, której transakcji dotyczy komunikat

Każda płatność powinna być jednoznacznie powiązana z własnym zamówieniem lub dokumentem.

4. Uwzględniaj wielokrotne powiadomienia

System powinien być odporny na ponowne otrzymanie informacji o tej samej transakcji.

Przykładowo drugi webhook dotyczący tego samego zamówienia nie powinien spowodować ponownego:

5. Prowadź logi

Warto zapisywać przynajmniej:

Przy analizowaniu reklamacji klienta takie dane są niezwykle pomocne.

Jak przetestować integrację z PayU?

Nie powinno się testować nowej integracji wyłącznie na rzeczywistych płatnościach.

PayU udostępnia środowisko testowe Sandbox. Przy bardziej rozbudowanych scenariuszach można utworzyć własne konto testowe i sprawdzić komunikację API bez obsługi rzeczywistych transakcji.

Testy powinny obejmować nie tylko udaną płatność.

Warto sprawdzić również:

Dopiero takie testy pokazują, czy integracja jest odporna na sytuacje występujące w rzeczywistym środowisku.

Jakie są największe korzyści integracji z PayU?

Szybsza płatność dla klienta

Klient nie musi samodzielnie wykonywać klasycznego przelewu.

Mniej błędów w przelewach

Kwota i identyfikator transakcji są przekazywane automatycznie.

Automatyczna identyfikacja płatności

System może od razu wiedzieć, czego dotyczy dana transakcja.

Szybsza realizacja zamówienia

Nie trzeba czekać, aż pracownik ręcznie sprawdzi rachunek bankowy.

Automatyzacja sprzedaży

Potwierdzenie płatności może uruchamiać kolejne procesy.

Lepsze doświadczenie klienta

Proces zakupowy staje się krótszy, szczególnie przy popularnych metodach takich jak BLIK.

Integracja z PayU przez gotowy moduł czy API?

Są dwa podstawowe podejścia.

Jeżeli firma korzysta ze standardowej platformy e-commerce, często nie ma potrzeby tworzenia całej integracji od początku.

Natomiast własny system SaaS, ERP, system fakturowy, marketplace czy dedykowany sklep może wymagać integracji bezpośrednio przez API.

PayU wskazuje REST API 2.1 jako standardową metodę komunikacji dla nowych integracji. Starszy Classic API nie jest aktywnie rozwijany i nie jest rekomendowany do nowych wdrożeń.

Najczęstsze błędy przy integracji z PayU

Problemy bardzo często nie dotyczą samego PayU, lecz logiki napisanej po stronie sklepu lub aplikacji.

Najczęściej spotykane są:

Dobra integracja nie powinna być projektowana wyłącznie pod scenariusz:

klient zapłacił i wszystko zadziałało.

Najwięcej uwagi trzeba poświęcić przypadkom, w których coś zostanie przerwane, powtórzone albo dostarczone z opóźnieniem.

Integracja PayU w praktyce – przykład

Załóżmy, że klient kupuje usługę za 299 zł.

System tworzy wewnętrzne zamówienie:

FV-2026-1257

Następnie tworzy transakcję w PayU i zapisuje identyfikator uzyskany od operatora.

Klient wybiera BLIK i zatwierdza płatność w aplikacji banku.

PayU zmienia status transakcji na COMPLETED i wysyła powiadomienie do systemu.

Aplikacja:

Cały proces może odbyć się automatycznie, bez udziału pracownika.

I właśnie na tym polega największa korzyść dobrej integracji z systemem płatności.

FAQ – najczęstsze pytania o integrację z PayU

Czy integracja z PayU jest trudna?

Podstawowe przekierowanie klienta do PayU nie jest szczególnie skomplikowane dla doświadczonego programisty. Więcej uwagi wymaga poprawna obsługa statusów, webhooków, błędów, zwrotów oraz nietypowych sytuacji.

Czy do integracji PayU potrzebny jest programista?

Jeżeli korzystasz z gotowego modułu przygotowanego dla konkretnej platformy, często wystarczy konfiguracja. Przy własnej aplikacji zazwyczaj potrzebne jest wdrożenie programistyczne.

Czy po kliknięciu „Zapłać” transakcję można od razu uznać za zapłaconą?

Nie. Utworzenie transakcji oznacza jedynie rozpoczęcie procesu. System powinien zaczekać na wiarygodne potwierdzenie jej odpowiedniego statusu.

Czy powrót klienta z PayU oznacza, że zapłacił?

Nie należy przyjmować takiego założenia. Do aktualizacji statusu płatności powinno się wykorzystywać komunikację pomiędzy PayU a systemem sprzedawcy.

Czy PayU wysyła informacje o zmianie statusu?

Tak. W przypadku prawidłowo skonfigurowanego notifyUrl PayU może przesyłać notyfikacje dotyczące zmian statusu zamówienia lub zwrotu.

Czy integracja może automatycznie oznaczyć fakturę jako opłaconą?

Tak, jeżeli system fakturowy posiada odpowiednią logikę. Po otrzymaniu informacji o zakończeniu płatności może odnaleźć odpowiednią fakturę i zmienić jej status.

Czy PayU obsługuje BLIK?

Tak. Dokumentacja PayU przewiduje kilka sposobów obsługi BLIK, w tym standardowe przekierowanie do płatności oraz bardziej zaawansowane warianty integracji.

Czy przez PayU można zrobić zwrot?

Tak. PayU obsługuje zwroty pełne i częściowe. W zależności od wdrożenia mogą być one wykonywane z wykorzystaniem API lub panelu.

Czy integrację można najpierw przetestować?

Tak. PayU udostępnia środowisko Sandbox przeznaczone do testowania integracji.

Podsumowanie

Integracja z PayU pozwala zrobić znacznie więcej niż tylko dodać do strony możliwość płatności online. Prawidłowo przygotowany mechanizm łączy zamówienie, płatność i dalszą obsługę w jeden automatyczny proces.

System tworzy transakcję, kieruje klienta do odpowiedniej metody płatności, odbiera informację o jej statusie i wykonuje zaprogramowane działania – na przykład oznacza fakturę jako opłaconą, rozpoczyna realizację zamówienia albo aktywuje usługę.

Najważniejszym elementem dobrego wdrożenia jest jednak nie sam przycisk „Zapłać”, ale obsługa całego cyklu życia transakcji: płatności zakończonych, oczekujących, anulowanych, ponawianych i zwracanych.

Dzięki temu integracja z PayU może ograniczyć ręczną pracę, przyspieszyć obsługę klientów i stać się jednym z elementów pełnej automatyzacji sprzedaży.