Webhooki płatności

Odbieranie powiadomień od dostawców i weryfikacja podpisów.

Dostawcy potwierdzają płatność, wysyłając powiadomienie na publiczny endpoint webhooka. Po weryfikacji podpisu API aktualizuje status zamówienia.

​

Endpoint

POST /api/v2/payments/webhooks/{provider}/{shopId}/{webhookSecret}

• provider — nazwa dostawcy (np. imojeTransfer, zen, paymentic)
• shopId — sklep, do którego należy metoda
• webhookSecret — sekret metody płatności (ustalany przy konfiguracji)

URL webhooka skonfiguruj po stronie dostawcy lub jest przekazywany automatycznie przy tworzeniu sesji.

​

Weryfikacja podpisu

Każdy dostawca podpisuje powiadomienie własnym sekretem i przekazuje podpis w nagłówku. ItemShop weryfikuje ten podpis na oryginalnej, niezmienionej treści żądania, zanim ją przetworzy. Mechanizm podpisu jest opisany w dokumentacji danego dostawcy:

Dostawca	Nagłówek podpisu
imoje	X-Imoje-Signature
ZEN	hash IPN przekazany w treści powiadomienia
Paymentic	X-Paymentic-Signature
Stripe	Stripe-Signature

Webhook z nieprawidłowym podpisem jest odrzucany. Weryfikacja działa na oryginalnej treści, dlatego nie modyfikuj powiadomienia po stronie proxy.

​

Mapowanie statusów

Dostawca przekazuje status transakcji, który API mapuje na status zamówienia:

Status dostawcy (przykłady)	Status zamówienia
settled, ACCEPTED, PAID	paid (opłacone, gotowe do realizacji)
cancelled, rejected, FAILED, EXPIRED	cancelled
pending, CREATED	brak akcji

Po przejściu w paid ItemShop automatycznie wysyła e-mail potwierdzający oraz powiadomienie na Discord.

​

Odpowiedź

Po pomyślnym przetworzeniu endpoint zwraca 200 z { "received": true }. Dostawcy traktują kod 2xx jako potwierdzenie odbioru.