{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Struktura i obsługa powiadomienia IPN","description":"Znajdziesz tutaj wszystkie niezbędne informacje dotyczące integracji i obsługi systemu płatności SimPay.pl","siteUrl":"https://docs.simpay.pl","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"struktura-i-obsługa-powiadomienia-ipn","__idx":0},"children":["Struktura i obsługa powiadomienia IPN"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Każde powiadomienie IPN (Webhook) wysyłane przez system SimPay posiada spójną, bazową strukturę. Niezależnie od tego,"," ","jakiego zdarzenia dotyczy powiadomienie (np. dokonana wpłata czy zwrot), przesyłane żądanie zawsze składa się z tych samych"," ","nagłówków HTTP oraz głównych elementów JSON – swoistej \"koperty\"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"nagłówki-http-headers","__idx":1},"children":["Nagłówki HTTP (Headers)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Każde żądanie POST wysyłane przez nasze serwery będzie zawierało następujące nagłówki. Zwróć uwagę na ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User-Agent"]},","," ","który może posłużyć jako pierwszy, wstępny (choć niewystarczający do pełnego bezpieczeństwa) filtr odrzucający ruch z"," ","botów:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Nagłówek"},"children":["Nagłówek"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Wartość"},"children":["Wartość"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["User-Agent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SimPay-IPN/2.0"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"wymagania-techniczne","__idx":2},"children":["Wymagania techniczne"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aby Twój system mógł prawidłowo odbierać powiadomienia od SimPay, musi spełniać kilka rygorystycznych warunków"," ","technicznych:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Dostępność publiczna:"]}," Twój endpoint IPN musi być wystawiony w publicznej sieci Internet. Powiadomienia nie dotrą"," ","na środowiska lokalne (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["localhost"]},"), chyba że użyjesz narzędzi typu ngrok."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Szybka odpowiedź:"]}," Czas oczekiwania naszego serwera na odpowiedź jest ograniczony. Ciężkie operacje (wysyłka"," ","e-maili, generowanie PDF) bezwzględnie deleguj do systemów kolejkowych pracujących w tle."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Poprawna odpowiedź HTTP:"]}," Oczekujemy konkretnej odpowiedzi potwierdzającej odebranie żądania. Twój serwer musi"," ","zwrócić jedną z poniższych opcji:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP 200 OK"]}," z nagłówkiem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: text/plain"]}," oraz ciałem odpowiedzi zawierającym wyłącznie słowo"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OK"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP 202 Accepted"]}," lub ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP 204 No Content"]}," (bez ciała odpowiedzi / pusty response)."]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rekomendowana-kolejność-obsługi","__idx":3},"children":["Rekomendowana kolejność obsługi"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aby zapewnić maksymalne bezpieczeństwo i wydajność, rekomendujemy obsługę każdego przychodzącego powiadomienia w"," ","dokładnie takiej kolejności:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Weryfikacja adresu IP"]}," – sprawdź, czy adres IP nadawcy znajduje się na naszej liście autoryzowanych adresów."," ","Odrzuć żądanie, jeśli IP nie pasuje."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Weryfikacja sygnatury"]}," – przelicz hash z otrzymanych danych i porównaj go z polem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature"]},". Zyskasz 100%"," ","pewności, że nikt nie zmodyfikował ładunku w locie."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rozpoznanie typu (routing)"]}," – odczytaj wartość z pola ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," i na jej podstawie oddeleguj dane (z obiektu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},")"," ","do asynchronicznej kolejki w Twoim systemie (Queue/Worker)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Zakończenie połączenia"]}," – natychmiast po wysłaniu zadania w tło, zwróć do nas poprawną odpowiedź (np."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK text/plain"]},"), zamykając połączenie z serwerem SimPay."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"struktura-json-koperta","__idx":4},"children":["Struktura JSON (Koperta)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Gdy Twój endpoint odbierze żądanie, jego ciało (body) będzie zawierać następujące pola:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Pole"},"children":["Pole"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Typ"},"children":["Typ"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Opis"},"children":["Opis"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," (Enum)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Typ przesyłanego zdarzenia (np. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction:status_changed"]},"). Na jego podstawie wiesz, jakiego schematu spodziewać się w polu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["char(36)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unikalny identyfikator (UUID) konkretnej notyfikacji. Pozwala na zapobieganie przetwarzaniu tego samego powiadomienia wielokrotnie."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}," (ISO 8601)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Data i godzina wygenerowania/wysyłki notyfikacji przez nasz system (np. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2025-05-20T16:36:07Z"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Obiekt zawierający szczegółowe dane biznesowe dotyczące konkretnego zdarzenia."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Podpis kryptograficzny (hash SHA-256) wygenerowany z wartości pól. Służy do weryfikacji autentyczności powiadomienia."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"przykładowe-żądanie-request","__idx":5},"children":["Przykładowe żądanie (Request)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /twoj-endpoint-ipn HTTP/1.1\nHost: twoj-sklep.pl\nContent-Type: application/json\nUser-Agent: SimPay-IPN/2.0\n\n// przesyłane body nie jest formatowane (nie zawiera spacji, nowych linii itp.)\n{\n  \"type\": \"transaction:status_changed\",\n  \"notification_id\": \"0196fec6-7a61-7219-9458-bcc45237c252\",\n  \"date\": \"2025-05-23T22:12:22+02:00\",\n  \"data\": {\n    \"id\": \"dbc87423-b121-4ad4-977f-b63c3d3831e8\",\n    \"payer_transaction_id\": \"Q68KLAKN\",\n    \"service_id\": \"e65c7519\",\n    \"status\": \"transaction_failure\",\n    \"amount\": {\n      \"final_currency\": \"PLN\",\n      \"final_value\": \"8.00\",\n      \"original_currency\": \"PLN\",\n      \"original_value\": \"8.00\",\n      \"commission_system\": \"0.06\",\n      \"commission_partner\": \"7.94\",\n      \"commission_currency\": \"PLN\"\n    },\n    \"control\": \"3e63e31d-f08d-4942-a223-3bad2dce8096\",\n    \"payment\": {\n      \"channel\": \"blik\",\n      \"type\": \"blik\"\n    },\n    \"customer\": {\n      \"country_code\": null\n    },\n    \"created_at\": \"2024-08-10T15:41:50+02:00\"\n  },\n  \"signature\": \"095a7be5d77c4bab667dbd0f35d9b1cb0c9cec50d8af42842cc37a95b233925e\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"co-dalej","__idx":6},"children":["Co dalej?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Kiedy znasz już bazową strukturę, czas wdrożyć zabezpieczenia i zapoznać się z konkretnymi danymi, które wysyłamy:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["👉 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/notifications/payment/signature"},"children":["Weryfikacja sygnatury i bezpieczeństwo"]}]}," – dowiedz się, jak poprawnie wyliczyć i"," ","zweryfikować hash w kroku 2."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["👉 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/notifications/payment/events/transaction_status_changed"},"children":["Zdarzenie: transaction:status_changed"]}]}," – zobacz strukturę pola ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," dla"," ","najważniejszego eventu dotyczącego opłacenia transakcji."]}]},"headings":[{"value":"Struktura i obsługa powiadomienia IPN","id":"struktura-i-obsługa-powiadomienia-ipn","depth":1},{"value":"Nagłówki HTTP (Headers)","id":"nagłówki-http-headers","depth":2},{"value":"Wymagania techniczne","id":"wymagania-techniczne","depth":2},{"value":"Rekomendowana kolejność obsługi","id":"rekomendowana-kolejność-obsługi","depth":2},{"value":"Struktura JSON (Koperta)","id":"struktura-json-koperta","depth":2},{"value":"Przykładowe żądanie (Request)","id":"przykładowe-żądanie-request","depth":3},{"value":"Co dalej?","id":"co-dalej","depth":2}],"frontmatter":{"seo":{"title":"Struktura i obsługa powiadomienia IPN"}},"lastModified":"2026-04-21T23:37:53.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/notifications/payment/structure","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}