Notyfikacje
Wprowadzenie
Notyfikacje to żądania wysyłane przez HotPay do serwera sprzedawcy z informacją o statusie płatności. Na ich podstawie można zaktualizować zamówienie i udostępnić opłaconą usługę.
Potwierdzenie płatności
Powrót klienta na stronę sklepu nie jest potwierdzeniem zapłaty. Realizuj zamówienie dopiero po sprawdzeniu autentyczności notyfikacji, zgodności danych z zamówieniem oraz statusu oznaczającego zaakceptowaną płatność.
Konfiguracja odbioru
- Przygotuj publicznie dostępny adres HTTPS w swojej aplikacji, np.
https://sklep.example.com/hotpay/notyfikacje. - W ustawieniach usługi w panelu HotPay podaj ten adres jako adres notyfikacji.
- Zapisz po stronie serwera sekret usługi (
SEKRET) oraz hasło notyfikacji z ustawień tej usługi (HASLO_Z_USTAWIEN). Są to dwie różne wartości. - Dopuść połączenia z adresów IP wymienionych poniżej i zaimplementuj weryfikację danych oraz obsługę ponowień.
Adres notyfikacji powinien przyjmować żądania bez logowania użytkownika, sesji przeglądarki i przekierowań. Jeżeli aplikacja wymaga tokenu CSRF dla formularzy, skonfiguruj wyjątek dla tego endpointu i uwierzytelniaj żądania przez weryfikację HASH.
Format żądania
Żądanie do serwera sprzedawcy
Adres URL: adres notyfikacji podany w ustawieniach usługi
Metoda: POST
Content-Type: multipart/form-data
Potwierdzenie odbioru: HTTP 200
Pola są przekazywane jako dane formularza. W PHP są dostępne w tablicy $_POST.
Adresy IP
Lista dozwolonych adresów IP
Notyfikacje są wysyłane z następujących adresów IP. Dopuść je w konfiguracji zapory, hostingu lub innych mechanizmów ograniczających dostęp do adresu notyfikacji:
- 18.197.55.26
- 3.126.108.86
- 3.64.128.101
- 18.184.99.42
- 3.72.152.155
- 35.159.7.168
Sprawdzenie adresu IP jest dodatkowym zabezpieczeniem. Każdą notyfikację należy również zweryfikować za pomocą pola HASH.
Weryfikacja HASH
Oblicz skrót SHA-256 z hasła notyfikacji oraz wartości pól w podanej kolejności względem wybranego typu płatności, rozdzielonych pojedynczym średnikiem (;). Wynik porównaj z otrzymanym polem HASH.
HASLO_Z_USTAWIEN oznacza hasło notyfikacji zapisane po stronie serwera. Hasło nie jest polem przychodzącego żądania.
Do obliczenia skrótu użyj dokładnych wartości odebranych pól. Nie zmieniaj zapisu kwoty (np. 10.00 na 10), nie usuwaj białych znaków i nie zmieniaj wielkości liter. Nawet taka zmiana spowoduje obliczenie innego skrótu.
Po pozytywnym wyniku weryfikacji sprawdź, czy ID_ZAMOWIENIA wskazuje istniejące zamówienie, kwota zgadza się z oczekiwaną, a status jest obsługiwany dla tej usługi. Kwoty porównuj jako wartości dziesiętne lub całkowitą liczbę groszy, bez używania liczb zmiennoprzecinkowych. Te porównania wykonuj osobno od obliczania HASH.
Potwierdzenie odbioru i ponowienia
Po poprawnej weryfikacji i trwałym zapisaniu wyniku obsługi notyfikacji zwróć HTTP 200. Dotyczy to także poprawnie obsłużonych statusów oczekujących, odrzuconych i zdarzeń subskrypcji.
HTTP 200 a status płatności
Kod HTTP 200 potwierdza odbiór notyfikacji przez aplikację. O wyniku płatności decyduje zweryfikowane pole STATUS.
Jeśli adres odbiorcy nie zwróci HTTP 200, może nastąpić ponowienie notyfikacji. Przygotuj aplikację na wielokrotne odebranie tych samych danych:
- Zapisuj identyfikator płatności i obsłużone zdarzenia. Ponowne otrzymanie tej samej notyfikacji nie powinno drugi raz udostępniać usługi ani zwiększać salda.
- Sprawdzenie, czy zamówienie zostało już zrealizowane, oraz zapis realizacji wykonuj atomowo, np. w transakcji bazy danych, aby zabezpieczyć również równoległe żądania.
- Dla poprawnej notyfikacji obsłużonej wcześniej również zwróć HTTP 200.
- Uwzględnij zmianę statusu tej samej płatności, np.
PENDING→SUCCESS. Samo wcześniejsze zapisanieID_PLATNOSCInie jest powodem do pominięcia kolejnego statusu. - Nie cofaj zrealizowanego zamówienia automatycznie po odebraniu opóźnionej notyfikacji ze statusem oczekującym.
Przy błędzie weryfikacji odrzuć żądanie bez realizacji zamówienia. Przy błędzie zapisu nie potwierdzaj obsługi kodem HTTP 200. Zapisuj informacje diagnostyczne bez ujawniania hasła notyfikacji.
Rozwiązywanie problemów
| Problem | Co sprawdzić |
|---|---|
| Notyfikacja nie dociera. | Adres w ustawieniach właściwej usługi, dostępność endpointu z internetu, certyfikat HTTPS i reguły zapory dla wszystkich adresów IP z listy. |
Endpoint zwraca przekierowanie, 403 lub 404. |
Zgodność ścieżki URL, wymaganie logowania, ochronę CSRF i reguły serwera lub hostingu blokujące żądania. |
Weryfikacja HASH kończy się błędem. |
Hasło notyfikacji, sekret usługi, wariant wzoru z SECURE lub bez niego, kolejność pól i zachowanie oryginalnego zapisu kwoty. |
| Ta sama notyfikacja przychodzi ponownie. | Czy po zapisie aplikacja zwraca HTTP 200 i czy odpowiedź dociera do nadawcy; upewnij się też, że ponowna obsługa nie powiela realizacji zamówienia. |