{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Powiadomienia IPN - DirectBilling","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":"powiadomienia-ipn---directbilling","__idx":0},"children":["Powiadomienia IPN - DirectBilling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["System SimPay pozwala na asynchroniczne informowanie Twojej aplikacji o zmianach statusu płatności DirectBilling ("," ","płatności doliczanych do rachunku u operatora komórkowego). Powiadomienia te wysyłane są za pomocą żądań HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," z"," ","ciałem w formacie ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["W odróżnieniu od Płatności Online, notyfikacje DirectBilling używają jednej spójnej struktury – powiadomienie po prostu"," ","aktualizuje status dla konkretnego ID transakcji."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"oczekiwana-odpowiedź-serwera","__idx":1},"children":["Oczekiwana odpowiedź serwera"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Aby powiadomienie zostało uznane za poprawnie doręczone, Twój serwer IPN musi ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["bezwzględnie"]}," zwrócić w ciele (body)"," ","odpowiedzi zwykły tekst (plaintext) ze słowem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OK"]}," oraz kodem statusu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HTTP 200"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"struktura-powiadomienia-json","__idx":2},"children":["Struktura powiadomienia (JSON)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Każde powiadomienie POST zawiera poniższe informacje w swoim ciele:"]},{"$$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":"th","attributes":{"align":"left","data-label":"Przykładowa wartość"},"children":["Przykładowa 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":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unikalne ID transakcji w systemie SimPay"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["serviceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Identyfikator Twojej usługi"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["e14f8074"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Aktualny status transakcji DirectBilling"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_payed"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Obiekt z wartościami kwotowymi"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values.net"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Kwota transakcji netto"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["11.07"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values.gross"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Kwota transakcji brutto"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["13.61"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values.partner"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Twoja prowizja (zarobek z transakcji)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returns"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Obiekt z adresami powrotnymi podanymi przy generowaniu transakcji"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returns.complete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Adres, na który klient miał trafić po sukcesie"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://www.simpay.pl/complete"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returns.failure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Adres, na który klient miał trafić po błędzie"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://www.simpay.pl/failure"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["control"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Twoje opcjonalne pole (przesyłane, jeśli zostało podane przy generowaniu)"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zamowienie_123"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["number_from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Numer telefonu kupującego, z którego obciążono rachunek"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["48123123123"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["provider"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Identyfikator operatora GSM"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]}]},{"$$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"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a3116cf..."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"dostępne-statusy-transakcji","__idx":3},"children":["Dostępne statusy transakcji"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["W powiadomieniach IPN dla DirectBilling możesz spotkać się z następującymi wartościami w polu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_new"]}]}," – transakcja została poprawnie utworzona w systemie."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_confirmed"]}]}," – transakcja potwierdzona przez operatora (np. klient przepisał prawidłowy PIN),"," ","oczekuje na ostateczne ściągnięcie środków."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_payed"]}]}," – transakcja poprawnie opłacona (ostateczny sukces)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_rejected"]}]}," – transakcja ostatecznie odrzucona przez operatora (np. brak wystarczających środków na"," ","koncie lub aktywna blokada usług Premium na numerze klienta)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_canceled"]}]}," – transakcja została anulowana (np. z powodu upływu czasu na wpisanie kodu PIN lub"," ","anulowania przez samego użytkownika)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_generate_error"]}]}," – wystąpił błąd podczas próby wygenerowania transakcji bezpośrednio u"," ","operatora GSM."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Wskazówka"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Gdy otrzymasz powiadomienie IPN, zawsze weryfikuj pole ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},". Oczekiwana wartość dla zakończonego sukcesem procesu"," ","DirectBilling (na podstawie którego wydajesz towar lub usługę) to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_payed"]}]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"przykładowy-payload-json","__idx":4},"children":["Przykładowy Payload JSON"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poniżej znajduje się zrzut kompletnego powiadomienia wysyłanego dla udanej transakcji (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_db_payed"]},")."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a\",\n  \"serviceId\": \"e14f8074\",\n  \"status\": \"transaction_db_payed\",\n  \"values\": {\n    \"net\": 11.07,\n    \"gross\": 13.61,\n    \"partner\": 5\n  },\n  \"returns\": {\n    \"complete\": \"https://www.simpay.pl/complete\",\n    \"failure\": \"https://www.simpay.pl/failure\"\n  },\n  \"number_from\": \"48123123123\",\n  \"provider\": 1,\n  \"signature\": \"a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obliczanie-sygnatury","__idx":5},"children":["Obliczanie sygnatury"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Weryfikacja sygnatury kryptograficznej to absolutny wymóg, aby upewnić się, że powiadomienie faktycznie pochodzi od"," ","SimPay."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sygnaturę generujemy poprzez zestawienie ze sobą wszystkich odebranych parametrów (z pominięciem pola ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature"]},") w"," ","dokładnie takiej kolejności, w jakiej występują w tabeli dokumentacji. Wartości należy oddzielić separatorem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|"]}," i na"," ","samym końcu dodać Twój klucz IPN usługi DirectBilling (dostępny w panelu klienta). Jeśli jakieś pole opcjonalne (np."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["control"]},") nie przyszło w żądaniu – po prostu je pomijasz."]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":["Zobacz wyliczenie sygnatury z powyższego przykładu"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Zakładamy, że testowy klucz usługi to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["klucz"]},")"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tworzymy ciąg znaków, oddzielając wartości separatorem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|"]},":"," ","Nasz bazowy ciąg będzie wyglądać tak:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_db_payed|11.07|13.61|5|https://www.simpay.pl/complete|https://www.simpay.pl/failure|48123123123|1\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Uwaga: w JSONie brakuje opcjonalnego pola ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["control"]},", więc całkowicie je pominęliśmy)."]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Dodajemy na końcu nasz klucz IPN:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["...|klucz"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Obliczamy SHA256 z powyższego ciągu i kodujemy w hex:"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"php","header":{"controls":{"copy":{}}},"source":"<?php\n\n$signature = hash('sha256', 'dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_db_payed|11.07|13.61|5|https://www.simpay.pl/complete|https://www.simpay.pl/failure|48123123123|1|klucz');\n","lang":"php"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":4},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Otrzymany hash (w tym przypadku ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a3116cf4f1e960223c2cc3088bf387278b6675255209bdeaf96a2f316a2fadc1"]},") powinieneś"," ","bezpiecznie porównać z wartością przesłaną w polu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["signature"]},"."]}]}]}]},"headings":[{"value":"Powiadomienia IPN - DirectBilling","id":"powiadomienia-ipn---directbilling","depth":1},{"value":"Oczekiwana odpowiedź serwera","id":"oczekiwana-odpowiedź-serwera","depth":2},{"value":"Struktura powiadomienia (JSON)","id":"struktura-powiadomienia-json","depth":2},{"value":"Dostępne statusy transakcji","id":"dostępne-statusy-transakcji","depth":3},{"value":"Przykładowy Payload JSON","id":"przykładowy-payload-json","depth":2},{"value":"Obliczanie sygnatury","id":"obliczanie-sygnatury","depth":2}],"frontmatter":{"seo":{"title":"Powiadomienia IPN - DirectBilling"}},"lastModified":"2026-05-12T14:09:20.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/notifications/directbilling","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}