Notyfikacje (Instant Payment Notification), powszechnie nazywane Webhookami, to najszybszy i najbezpieczniejszy sposób na automatyczną komunikację między SimPay a Twoim systemem. Zamiast ciągłego, ręcznego odpytywania naszego API o to, czy klient opłacił zamówienie (tzw. polling), to system SimPay proaktywnie informuje Ciebie, gdy tylko nastąpi jakakolwiek zmiana statusu transakcji, zwrotu, subskrypcji, czy aliasu BLIK.
Powiadomienia są wysyłane jako asynchroniczne żądania HTTP z metodą POST prosto na Twój adres URL IPN, który wcześniej skonfigurujesz w Panelu Partnera SimPay. Wszystkie dane dotyczące zdarzenia przesyłane są w ciele żądania (body) w uniwersalnym formacie JSON.
Kiedy wyślemy do Ciebie powiadomienie, oczekujemy natychmiastowego potwierdzenia, że zostało ono odebrane.
Twój serwer musi zwrócić odpowiedź z kodem statusu z grupy HTTP 2XX. W przypadku zwrócenia kodu 200 musisz zwrócić dodatkowo w body odpowiedź OK. W przypadku zwrócenia kodów 202 lub 204 nie musisz zwracać żadnej treści w body.
Każda inna odpowiedź (np. kody błędów 4xx, 5xx) lub brak odpowiedzi (przekroczenie limitu czasu / timeout) zostanie przez nas potraktowana jako błąd doręczenia.
Zwracaj status 200 OK natychmiast po odebraniu i autoryzacji powiadomienia. Jeśli obsługa zamówienia (np. generowanie faktury, komunikacja z magazynem) zajmuje więcej czasu, przekaż to zadanie do kolejki w tle w swojej aplikacji. Dzięki temu unikniesz sytuacji, w której SimPay przerwie połączenie z powodu zbyt długiego oczekiwania na odpowiedź.
Awarie sieci czy chwilowe przerwy techniczne serwerów to normalna rzecz. Jeśli Twój endpoint nie zwróci prawidłowego statusu 2XX, nasz system nie porzuca powiadomienia od razu. Zostanie ono zakolejkowane i wysłane ponownie.
W przypadku błędu, kolejne próby doręczenia powiadomienia IPN realizowane są zazwyczaj według następującego harmonogramu:
- Ponowienia 1-11: co minutę
- Ponowienia 12-16: co 5 minut
- Ponowienia 17-21: co 30 minut
- Ponowienia 22-30: co godzinę
Jeżeli po wyczerpaniu wszystkich prób Twój serwer nadal nie odpowie poprawnie, powiadomienie zostanie trwale oznaczone jako niedoręczone.
Aby prawidłowo zintegrować odbieranie powiadomień IPN, musisz wiedzieć, jakich danych się spodziewać oraz jak upewnić się, że żądanie na 100% pochodzi od SimPay, a nie od oszusta.
Przygotowaliśmy na to trzy dedykowane sekcje:
👉 Sprawdź: Struktura powiadomienia IPN – dowiedz się, jak dokładnie wygląda przesyłany przez nas JSON i jakie obiekty zawiera.
👉 Sprawdź: Weryfikacja sygnatury i bezpieczeństwo – zobacz, jak w prosty sposób zweryfikować podpis kryptograficzny dołączany do każdego powiadomienia, aby chronić swój system przed atakami.
👉 Sprawdź: Weryfikacja adresów IP – waliduj adres IP, z którego przychodzi IPN, aby uniknąć oszustw i nieautoryzowanych prób dostępu do IPN.