# Wprowadzenie do Notyfikacji IPN Płatności Online

## Co to są notyfikacje?

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.

## Jak wysyłamy powiadomienia?

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**.

## Czego oczekujemy w odpowiedzi?

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.

Dobra praktyka
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ź.

## Ile razy i co jaki czas ponawiamy wysyłkę?

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:*

1. Ponowienia 1-11: **co minutę**
2. Ponowienia 12-16: **co 5 minut**
3. Ponowienia 17-21: **co 30 minut**
4. 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.

## Co dalej? Zadbaj o strukturę i bezpieczeństwo

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](/notifications/payment/structure)** – dowiedz się, jak dokładnie wygląda przesyłany
przez nas JSON i jakie obiekty zawiera.

👉 **[Sprawdź: Weryfikacja sygnatury i bezpieczeństwo](/notifications/payment/signature)** – 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](/notifications/payment/ip-validation)** – waliduj adres IP, z którego przychodzi
IPN, aby uniknąć oszustw i nieautoryzowanych prób dostępu do IPN.