Jak zintegrować Payora z własną stroną w PHP

Jak połączyć Payora z własną stroną internetową w PHP

Jeśli Twoja strona działa na samodzielnie napisanym PHP, sprawa jest prosta: utwórz płatność, przekieruj klienta do Payora, a potem przekaż wynik z powrotem do własnego systemu zamówień. Bez WooCommerce. Bez plątaniny wtyczek.

W tym poradniku pokazujemy, jak zintegrować Payora z PHP, nie zamieniając procesu płatności w projekt naukowy. Dowiesz się, w którym miejscu PHP powinno rozpocząć płatność, gdzie odebrać powrót klienta i jak aplikacja ma ustalić, czy zamówienie jest opłacone, oczekujące czy nieudane.

1. Wybierz sposób integracji dla własnej strony w PHP

Na początek zdecyduj, czy tworzysz prosty link do płatności, żądanie płatności obsługiwane po stronie serwera, czy pełny proces płatności z monitorowaniem zamówienia. To nie to samo. Prosta, jednostronicowa witryna zbierająca datki może korzystać z linku do płatności, ale sklep z 20 produktami zwykle powinien utworzyć zamówienie po stronie serwera, zanim klient opuści stronę.

W przypadku własnej strony w PHP najczyściej wygląda to tak: utwórz zamówienie lokalnie, zainicjuj płatność Payora z poziomu PHP, przekieruj klienta, a następnie obsłuż jego powrót i potwierdzenie z serwera. Dzięki temu masz zapis zamówienia, zanim ruszą pieniądze. Logika koszyka i faktur pozostaje też w Twojej aplikacji, tam gdzie jej miejsce. Taki właśnie przebieg opisuje integracja płatności Payora na własnej stronie.

Jeśli proces płatności jest prosty, może wystarczyć przekierowanie na stronę płatności hostowaną przez Payora. Jeśli potrzebujesz pozycji zamówienia, uwag klienta lub identyfikatorów zamówień, Twój kod PHP powinien przesłać te dane przed przekierowaniem. Prosto, ale nie prostacko.

Przyda się konkretny przykład. Agencja cyfrowa sprzedająca trzyetapowy pakiet usług serwisowych może utworzyć zamówienie w PHP, dodać adres e-mail klienta i przekierować go do Payora z numerem faktury. Hobbystyczny projekt sprzedający pojedynczy klucz licencyjny może potrzebować jedynie linku do płatności i strony powrotu. Różnica zależy od tego, ile informacji o stanie trzeba zachować, a nie od ilości kodu.

2. Rozplanuj strony, endpointy i obsługę sesji

Zanim zaczniesz pisać kod, rozpisz strony. Potrzebujesz co najmniej trzech: strony płatności, strony powrotu oraz endpointu serwerowego do potwierdzania płatności. Jeśli pominiesz ten etap, będziesz zgadywać, które żądanie zmieniło status zamówienia. Zgadywanie kosztuje.

W obsłudze przeglądarki użyj standardowej sesji PHP, ale nie polegaj wyłącznie na niej. Dane sesji mogą zniknąć, jeśli klient zmieni urządzenie, zamknie kartę albo wróci z Payora później. Zapisz identyfikator zamówienia również w bazie danych, aby kod PHP mógł odnaleźć transakcję nawet wtedy, gdy sesja przeglądarki już nie istnieje.

Typowy przebieg wygląda tak:

• Strona płatności zbiera informacje o produkcie, adresie e-mail i liczbie sztuk.
• PHP tworzy lokalne zamówienie ze statusem oczekujące.
• PHP przekierowuje klienta do Payora.
• Payora przekierowuje przeglądarkę z powrotem na adres URL powrotu.
• Serwer sprawdza status płatności, zanim oznaczy zamówienie jako opłacone.

Taki przebieg pozwala oddzielić stronę powrotu w przeglądarce od stanu ustalanego po stronie serwera. I słusznie — powinny być oddzielone. Przeglądarka może powiedzieć, co zobaczył klient, ale to serwer powinien ustalić, co oznacza to dla zamówienia.

Jeden drobny nawyk może później zaoszczędzić wiele godzin: od razu po utworzeniu płatności zapisz referencję płatności Payora obok identyfikatora zamówienia. Jeśli zrobisz to dopiero po przekierowaniu, błąd sieci albo niecierpliwe odświeżenie strony może zostawić zamówienie bez referencji Payora. Wtedy zaczyna się dochodzenie na produkcji.

3. Przygotuj podstawową warstwę obsługi żądań płatności w PHP

Nie umieszczaj kodu płatności w szablonach. Wystarczy niewielka klasa lub funkcja pomocnicza w PHP. Jedna metoda może budować dane żądania, druga wysyłać żądanie HTTP, a trzecia analizować odpowiedź. Taki podział ma znaczenie, bo logika płatności zmienia się częściej niż wygląd strony.

Na przykład funkcja pomocnicza może przyjmować tablicę zawierającą amount, currency, order_id i return_url, a następnie dodawać dane dostępowe Payora pobrane ze zmiennych środowiskowych. Strona płatności nie powinna wiedzieć, gdzie znajduje się token API. Powinna jedynie wiedzieć, który przycisk został kliknięty.

Oto zarys logiki kodu, a nie kompletna implementacja:

1. Pobierz zamówienie z bazy danych.
2. Przygotuj tablicę żądania do Payora.
3. Wyślij żądanie za pomocą cURL lub podobnego klienta HTTP.
4. Zapisz zwróconą referencję płatności Payora.
5. Przekieruj klienta na adres URL płatności Payora.

Niech ta funkcja pomocnicza będzie prosta i przewidywalna. Taki kod łatwiej testować i rzadziej zawodzi, gdy zmienisz cenę produktu albo dodasz w przyszłym miesiącu drugi formularz płatności.

Jeśli Twoja aplikacja ma już warstwę abstrakcji płatności, skorzystaj z niej. Jeśli nie, utwórz jeden plik i nadaj mu jasną nazwę, na przykład PayoraClient.php. Umieść w nim dane dostępowe, wywołania API i analizowanie odpowiedzi. Nic więcej. Żadnego HTML-a. Żadnego CSS-a. Żadnej wiadomości z podziękowaniem.

4. Przekieruj klienta do Payora z własnej strony płatności

Gdy lokalne zamówienie już istnieje, wyślij żądanie płatności do Payora i przekieruj klienta na stronę płatności. Przekierowanie powinno nastąpić dopiero po zapisaniu zamówienia przez serwer, ponieważ użytkownik może zamknąć kartę, gdy tylko się rozpocznie.

Przekazuj tylko te szczegóły zamówienia, których naprawdę potrzebujesz. Zwykle są to identyfikator zamówienia, kwota, waluta i adres e-mail klienta. Możesz też dodać metadane, takie jak nazwa produktu lub wewnętrzny identyfikator konta, ale nie wysyłaj wszystkich pól z bazy tylko dlatego, że są dostępne. Nadmiar danych może później utrudnić zespołowi pomocy porównywanie zapisów.

Własna strona płatności często korzysta z formularza POST z przyciskiem „Zapłać teraz”. Formularz wysyła dane do endpointu PHP, endpoint tworzy płatność w Payorze, a następnie zwraca przekierowanie. Klient nie widzi odpowiedzi API — widzi tylko Payora.

Jedna ważna uwaga: nie ufaj kwotom obliczanym po stronie przeglądarki. Jeśli strona produktu pokazuje 49 USD, a przeglądarka przesyła 39 USD, serwer musi odrzucić niezgodność. Żądanie płatności należy tworzyć na podstawie sumy zamówienia zapisanej po stronie serwera, a nie wartości ukrytej w formularzu. Ta zasada obowiązuje zawsze.

Jeśli chcesz poznać szerzej różne sposoby konfiguracji płatności, poradnik o bramce płatności kryptowalutowych dla e-commerce zawiera przydatne informacje i nie powtarza tutaj opisanego procesu w PHP.

5. Odbierz i zweryfikuj wynik płatności w swojej aplikacji

Adres URL powrotu w przeglądarce jest przydatny, ale nie stanowi ostatecznego potwierdzenia. Może wskazać, że odwiedzono stronę płatności, i przekazać status, jednak aplikacja PHP powinna traktować ten wynik jako wstępny, dopóki serwer go nie potwierdzi. Status oczekujący nie oznacza, że płatność została zrealizowana.

Strona powrotu powinna obsługiwać trzy przypadki: sukces, oczekiwanie i niepowodzenie. Jeśli Payora zwróci status sukcesu, pokaż stronę z podziękowaniem i poinformuj użytkownika, że zamówienie jest w trakcie potwierdzania. Jeśli status jest oczekujący, powiedz to wprost. Jeśli płatność się nie powiodła, zachęć klienta do ponownej próby, nie usuwając zapisu zamówienia. Jasne komunikaty ograniczają liczbę zgłoszeń do pomocy technicznej.

Warto pamiętać o jednej zasadzie: sama strona powrotu nie powinna oznaczać zamówienia jako opłaconego. Powinna jedynie wyświetlać aktualny stan i ewentualnie udostępniać link do strony zamówienia. Aktualizację bazy danych wykonuj po weryfikacji, a nie po przekierowaniu przeglądarki. To rozróżnienie chroni przed przypadkowymi, wielokrotnymi aktualizacjami.

Uprość endpoint powrotu tak, aby dało się go zrozumieć na pierwszy rzut oka. Jeśli otrzyma referencję płatności Payora, wyszukaj ją. Jeśli brakuje referencji, zapisz żądanie w logach i zakończ obsługę. Jeśli zamówienie jest już opłacone, wyświetl przyjazny komunikat i niczego nie zmieniaj. Dzięki temu wielokrotne odświeżanie strony nie zakłóca idempotentnego procesu.

Zespołom, które chcą też porównać rozwiązania od strony procesu płatności, przyda się artykuł o przyjmowaniu płatności kryptowalutowych — zwłaszcza jeśli sprzedają usługi z cyklicznymi fakturami lub ręczną akceptacją.

6. Potwierdź transakcję na serwerze, zanim oznaczysz zamówienie jako opłacone

To bezpieczniejsze rozwiązanie. Jeśli zastanawiasz się, jak potwierdzić płatność Payora w PHP, aplikacja powinna wysłać zapytanie do Payora z poziomu serwera i potwierdzić status transakcji, zanim oznaczy zamówienie jako opłacone. Przekierowanie w przeglądarce może nie przekazać całej prawdy. Weryfikacji serwerowej nie obchodzi, czy klient zamknął kartę, odświeżył stronę dwa razy albo użył drugiego urządzenia.

Użyj wcześniej zapisanej referencji płatności Payora, a następnie pobierz aktualny status transakcji. Porównaj zwrócony status ze statusem wymaganym do realizacji zamówienia. Jeśli transakcja jest rozliczona lub potwierdzona, zaktualizuj zamówienie. Jeśli nadal oczekuje, pozostaw zamówienie w tym stanie. Jeśli płatność się nie powiodła lub została anulowana, nie zmieniaj zamówienia.

Na marginesie: właśnie na tym etapie wiele własnych stron w PHP zaczyna działać byle jak. Twórcy ufają stronie powrotu, bo tak szybciej napisać kod. Szybciej — owszem. Bezpieczniej — nie. Pięć sekund na weryfikację jest zawsze lepsze niż późniejsza wymiana maili z pomocą techniczną.

Jeśli Payora udostępnia podpisane powiadomienie zwrotne lub mechanizm potwierdzania między serwerami, użyj go razem ze sprawdzeniem statusu. Dzięki temu masz dwa zabezpieczenia: jedno w procesie klienta, drugie w komunikacji serwerowej. Jeśli potrzebujesz instrukcji weryfikacji podpisu krok po kroku, zobacz, jak przetestować płatność kryptowalutową i wyrobić dobre nawyki weryfikacyjne przed uruchomieniem systemu.

Oznacz zamówienie jako opłacone dopiero wtedy, gdy potwierdzi to serwer. Nie wtedy, gdy twierdzi tak klient. Ani wtedy, gdy tak wynika z informacji w przeglądarce. Baza danych powinna odzwierciedlać status płatności potwierdzony przez Payora, bo właśnie temu statusowi będą później ufać zespoły realizacji zamówień i księgowości.

7. Zapisz dane płatności i obsłuż powielone żądania

Zapisz w bazie danych identyfikator transakcji Payora, lokalny identyfikator zamówienia, kwotę, walutę i końcowy status. Jeśli to możliwe, zrób to w ramach jednej operacji zapisu. Gdy klient napisze później „zapłaciłem dwa razy”, przyda Ci się przejrzysty zapis, a nie trzy niekompletne aktualizacje.

Powielone żądania zdarzają się z całkiem zwyczajnych powodów. Klient kliknie dwa razy. Użyje przycisku Wstecz. Przeglądarka ponowi żądanie. Kod PHP powinien wykryć, że zamówienie ma już referencję Payora, i nie tworzyć drugiej płatności za to samo zamówienie, chyba że pierwsza się nie powiodła lub wygasła. Na tym polega idempotencja.

Dobrze sprawdza się prosta zasada: jedno lokalne zamówienie — jedna aktywna transakcja Payora. Jeśli w trakcie oczekiwania na pierwszą płatność nadejdzie drugie żądanie dla tego samego zamówienia, pokaż istniejący link do płatności Payora zamiast tworzyć nowy. Jeśli zamówienie jest już opłacone, nie rób nic. Po cichu. To zaleta, nie wada.

Nazwij kolumny w bazie precyzyjnie. Na przykład użyj pól payora_reference, payment_status, paid_at i last_checked_at. Przydadzą się zespołom pomocy, księgowości i programistom podczas debugowania. Jeśli później trzeba będzie uzgodnić płatność, te cztery pola odpowiedzą na większość pytań bez godzinnego przeszukiwania logów.

Jeśli tworzysz obsługę faktur dla klientów, a nie sklepowy proces płatności, artykuł o bramce płatności kryptowalutowych dla freelancerów może pomóc w zastosowaniu tej samej logiki przechowywania danych — zwłaszcza gdy ważniejsze od koszyków są numery faktur.

8. Przetestuj cały proces na kopii testowej strony

Zanim uruchomisz system, skopiuj stronę do środowiska testowego i sprawdź cały proces: tworzenie zamówienia, przekierowanie do Payora, stronę powrotu, weryfikację serwerową i obsługę wielokrotnych kliknięć. Jeśli przetestujesz tylko przekierowanie, sprawdzisz zaledwie jedną trzecią problemu.

Wykonaj co najmniej te testy:

• Utwórz nowe zamówienie i sprawdź, czy generowane jest żądanie płatności Payora.
• Odśwież stronę powrotu 2 razy i sprawdź, czy status zamówienia nie zmieni się ponownie.
• Wyślij formularz płatności dwukrotnie i upewnij się, że istnieje tylko 1 aktywna transakcja.
• Wymuś wynik oczekujący lub nieudany i sprawdź, czy zamówienie pozostaje nieopłacone.
• Sprawdź, czy zapisana referencja Payora jest zgodna z rekordem w bazie danych.

Testuj na tej samej wersji PHP i konfiguracji serwera, których planujesz użyć na produkcji. Proces działający na lokalnym komputerze może zawieść na serwerze produkcyjnym z bardziej rygorystyczną konfiguracją SSL lub innymi ustawieniami cURL. To nic niezwykłego. Tak się zdarza.

Jeszcze jeden praktyczny test: otwórz zamówienie w oknie incognito, dokonaj płatności, a następnie otwórz ten sam adres powrotu w drugiej przeglądarce. Aplikacja nie powinna aktualizować płatności po raz drugi. Jeśli tak się dzieje, napraw to przed uruchomieniem. Bez wyjątków.

Zespołom oferującym płatności USDC obok innych metod przydadzą się wskazówki z artykułu o przyjmowaniu płatności USDC. Pomogą porównać oczekiwania klientów, zanim wdrożysz proces PHP na produkcji.

Na koniec sprawdź, czy to samo zamówienie przejdzie przez jedno przekierowanie, jedno odświeżenie i jedno potwierdzenie z serwera bez utraty zgodności danych. Jeśli tak, własny proces płatności w PHP jest gotowy na pierwszą rzeczywistą płatność.