Struktura notyfikacji

Każda notyfikacja z Paymentic to HTTP POST wysyłany na URL endpointu zdefiniowany w panelu. Request składa się z trzech części:

1. Linia startowa — metoda, ścieżka, wersja HTTP.
2. Nagłówki — zawierają metadane niezbędne do weryfikacji (sygnatura, typ zdarzenia, czas wysłania).
3. Body — payload w formacie JSON, różny w zależności od typu zdarzenia.

Przykładowy request

POST /yourpath HTTP/1.1
Host: yourdomain.com
User-Agent: Paymentic/1.1
Content-Type: application/json
Content-Length: 170
X-Paymentic-Event: PAYMENT.TRANSACTION_STATUS_CHANGED
X-Paymentic-Notification-Id: 01j96yn02bhbv8j1jjtk36zn2t
X-Paymentic-Time: 2024-09-20T09:48:03+02:00
X-Paymentic-Signature: 5Fil+PMpabLxsKwo3rWj9+o6gAi4ub93fismBewbYz46mHt7pjPHcHELUVw8McZ5nUb3feMVVBl+dPzXq2XgLQ==

{"transactionId":"FJRS-LY7-3W0-30K9","pointId":"000cb241","status":"CREATED","amount":10,"currency":"PLN","commission":null,"custom":null,"channelId":null}

Nagłówki

Paymentic wysyła następujące nagłówki przy każdej notyfikacji:

Nagłówek	Wymagany	Opis
User-Agent	Tak	Identyfikator systemu nadawczego w formacie Paymentic/{wersja} (np. Paymentic/1.1).
Content-Type	Tak	Zawsze application/json.
Content-Length	Tak	Długość body w bajtach.
X-Paymentic-Event	Tak	Typ zdarzenia, np. PAYMENT.TRANSACTION_STATUS_CHANGED. Po tej wartości rozpoznajesz, jak sparsować body.
X-Paymentic-Notification-Id	Tak	Unikalny identyfikator (ULID) tej konkretnej notyfikacji. Klucz idempotentności — zob. uwagi niżej.
X-Paymentic-Time	Tak	Czas wysłania notyfikacji w formacie ISO 8601 (np. 2024-09-20T09:48:03+02:00).
X-Paymentic-Signature	Tak	Sygnatura HMAC-SHA512 w Base64, służy do weryfikacji autentyczności — zob. Sygnatura.

User-Agent a wersja notyfikacji

Nagłówek User-Agent ma formę Paymentic/{wersja}, np. Paymentic/1.1 lub Paymentic/1.2. Część po slashu mówi Ci, w jakiej wersji schematu przychodzi body. Ten sam typ zdarzenia (PAYMENT.TRANSACTION_STATUS_CHANGED) ma nieco inne pola w wersji 1.1 i 1.2 — zob. Zmiana statusu transakcji.

uwaga

Wersja z nagłówka User-Agent jest też jednym ze składników sygnatury. Do liczenia HMAC bierzesz tylko samą wersję (np. 1.1), a nie całą wartość nagłówka. Szczegóły: Sygnatura.

X-Paymentic-Event

Lista aktualnie wysyłanych zdarzeń:

Wartość	Co oznacza	Struktura body
PAYMENT.TRANSACTION_STATUS_CHANGED	Zmiana statusu transakcji płatniczej	Zmiana statusu transakcji
PAYMENT.REFUND_STATUS_CHANGED	Zmiana statusu zwrotu	Zmiana statusu zwrotu
PAYMENT.TRANSACTION_BLIK_STATUS_CHANGED	Zmiana statusu transakcji BLIK (Level 0)	Zmiana statusu transakcji BLIK

W kodzie obsłuż te zdarzenia w switch-u po wartości tego nagłówka — unikniesz parsowania body pod zły schemat.

X-Paymentic-Notification-Id

Każda notyfikacja ma unikalne ID w formacie ULID. Użyj go do zapewnienia idempotentności — jeśli notyfikacja o tym samym ID już została pomyślnie obsłużona, kolejne wystąpienie (np. z powodu retry) powinno od razu zwrócić 200 OK bez modyfikowania stanu zamówienia.

ostrzeżenie

Ta sama notyfikacja może przyjść do Ciebie więcej niż raz — to normalne zachowanie (zob. Ponawianie notyfikacji). Zawsze sprawdzaj X-Paymentic-Notification-Id przed aktualizacją stanu zamówienia.

X-Paymentic-Time

Czas wysłania notyfikacji w formacie ISO 8601 z przesunięciem strefy czasowej. Użyteczny do:

• diagnostyki (wiesz, kiedy Paymentic próbował dostarczyć notyfikację),
• wykrywania opóźnień (czas między X-Paymentic-Time a momentem otrzymania webhooka = czas dostarczenia).

Wartość tego nagłówka jest składnikiem sygnatury — jeśli cokolwiek ją przepiszesz/zmodyfikujesz (np. jakiś proxy), weryfikacja nie przejdzie.

X-Paymentic-Signature

Sygnatura HMAC-SHA512 zakodowana w Base64. Służy do potwierdzenia, że notyfikacja pochodzi od Paymentic, a jej treść nie została zmieniona po drodze. Szczegóły wyliczania i przykłady w różnych językach: Sygnatura.

Bez weryfikacji sygnatury nie ufaj treści notyfikacji

Każdy, kto zna URL Twojego endpointu, może wysłać spreparowany POST z dowolnym body. Weryfikacja sygnatury to jedyny mechanizm, który potwierdza autentyczność notyfikacji.

Body

Body notyfikacji jest zawsze poprawnym JSON-em zakodowanym w UTF-8. Konkretny zestaw pól zależy od wartości X-Paymentic-Event i wersji z User-Agent.

Pola wspólne dla wszystkich zdarzeń płatniczych:

Pole	Typ	Opis
transactionId	string	Unikalny identyfikator transakcji w systemie Paymentic.
pointId	string	Identyfikator punktu płatności, na którym została utworzona transakcja.
status	string	Aktualny status zasobu (transakcji, zwrotu itd.).

Pełną specyfikację pól dla każdego zdarzenia znajdziesz w jego dedykowanej dokumentacji (linki w tabeli wyżej).

Body czytaj jako surowy string do momentu weryfikacji sygnatury

Sygnatura jest liczona na dokładnej zawartości body — bajt po bajcie. Jeśli Twój framework automatycznie parsuje JSON, a potem Ty serializujesz go z powrotem do stringa, kolejność pól i białe znaki mogą się zmienić, a sygnatura przestanie się zgadzać. Pracuj na surowym stringu z request body.

Wymagania dla endpointu partnera

Endpoint, na który Paymentic wysyła notyfikacje, musi spełniać następujące warunki:

• Publicznie dostępny — Paymentic nie dosięgnie localhost ani adresów z prywatnych zakresów IP.
• HTTPS — na produkcji wymagany; certyfikat musi być ważny (self-signed nie przejdzie).
• Akceptuje metodę POST — bez przekierowań (3xx są traktowane jako błąd).
• Nie wymaga uwierzytelnienia — nagłówków typu Authorization, cookie ani Basic Auth nie wyślemy.
• Odpowiada szybko — rekomendowane < 10 s (długie operacje przerzuć na kolejkę).
• Zwraca HTTP 200 OK z body OK (text/plain) lub HTTP 202 Accepted bez body — każda inna odpowiedź jest traktowana jako nieudane dostarczenie i włącza ponawianie.

Wymagana odpowiedź

HTTP/1.1 200 OK
Content-Type: text/plain

OK

lub:

HTTP/1.1 202 Accepted

Wersjonowanie notyfikacji

Paymentic wspiera obecnie dwie wersje schematu body:

Wersja	Status	Główna różnica
1.1	Wspierana (legacy)	Kwoty jako number, inne nazwy pól (custom, channelId).
1.2	Rekomendowana (aktualna)	Kwoty jako string (decimal) dla pełnej precyzji, nowe pola: externalReferenceId, paymentMethod, paymentChannel.

Wersja, w której otrzymujesz notyfikację, zależy od ustawień Twojego punktu płatności w panelu. Nowe integracje startuj od razu na 1.2.

Zalecana kolejność operacji w obsłudze webhooka

1. Odczytaj surowe body (bez parsowania JSON-a).
2. Zweryfikuj sygnaturę na surowym body + nagłówkach — jeśli się nie zgadza, zwróć 401 i zakończ.
3. Sprawdź X-Paymentic-Notification-Id — jeśli już przetwarzałeś, zwróć 200 OK i zakończ.
4. Sparsuj JSON i zrzut do modelu zależnego od X-Paymentic-Event.
5. Wykonaj logikę biznesową (aktualizacja statusu zamówienia itd.) — najlepiej asynchronicznie, w tle.
6. Zwróć 200 OK z body OK — szybko, nie czekając na zakończenie logiki biznesowej.
7. Zapisz X-Paymentic-Notification-Id jako przetworzony (idealnie w tej samej transakcji, co aktualizacja zamówienia).

Co dalej?

• Sygnatura — jak zweryfikować autentyczność notyfikacji (z przykładami kodu).
• Ponawianie notyfikacji — co się dzieje, gdy endpoint nie odpowie poprawnie.
• Zmiana statusu transakcji — struktura body dla PAYMENT.TRANSACTION_STATUS_CHANGED.