Bramka płatnicza: webhooki

Webhook to sposób, w jaki Paymove aktywnie powiadamia Twój system o zakończonej płatności - bez odpytywania API. Konfiguracja składa się z dwóch kroków: rejestrujesz webhook, a następnie przypisujesz go do produktu (sklepu). Od tego momentu każda opłacona transakcja w tym sklepie trafia na wskazany przez Ciebie endpoint. Wszystkie żądania autoryzujesz kluczem API przekazywanym w nagłówku X-API-KEY.

Przykłady używają środowiska sandbox: https://gateway-api.sandbox.paymove.io. Potrzebujesz partnerId oraz productId sklepu utworzonego w tutorialu Bramka płatnicza: podstawowa integracja.

Krok 1: Rejestracja webhooka

W requestTemplate definiujesz body żądania, które Paymove wyśle na Twój endpoint. Możesz w nim użyć zmiennych {{externalId}} (identyfikator zamówienia z Twojego systemu) i {{price}} (kwota) - Paymove podstawi je przy wysyłce.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "name": "OrderPaymentHook",
    "endpoint": "https://merchant-shop.com/api/payments/webhook",
    "method": "POST",
    "requestTemplate": {
      "orderId": "{{externalId}}",
      "price": "{{price}}"
    },
    "responseTemplate": { "status": "ok" },
    "expectedCode": 200,
    "expectedResponse": "{ \"status\": \"ok\" }",
    "retries": 3,
    "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "type": "PAYMENT",
    "headers": {
      "Authorization": ["Bearer abc123"],
      "Content-Type": ["application/json"]
    }
  }'

Pole	Opis
`name`	Nazwa webhooka (widoczna w konfiguracji).
`endpoint`	URL, na który Paymove wysyła żądanie.
`method`	Metoda HTTP (np. `POST`).
`requestTemplate`	Szablon body żądania (zmienne podstawiane przez Paymove).
`responseTemplate`	Oczekiwana struktura odpowiedzi od partnera.
`expectedCode`	Oczekiwany kod HTTP odpowiedzi (np. 200).
`expectedResponse`	Oczekiwana treść odpowiedzi (np. `{ "status": "ok" }`).
`retries`	Liczba ponownych prób przy niepowodzeniu. Domyślnie `0` - ustaw jawnie, jeśli chcesz ponawianie.
`partnerId`	Identyfikator partnera (nadawany przez Paymove).
`type`	Typ zdarzenia - dla powiadomień o płatności: `PAYMENT`.
`headers`	Nagłówki dołączane do żądania (np. `Authorization`, `Content-Type`).

Odpowiedź (200):

{
  "id": "6b23ecd9-14c8-47fc-add0-b71ec50e9d66",
  "name": "OrderPaymentHook",
  "endpoint": "https://merchant-shop.com/api/payments/webhook",
  "method": "POST",
  "requestTemplate": {
    "orderId": "{{externalId}}",
    "price": "{{price}}"
  },
  "responseTemplate": { "status": "ok" },
  "expectedCode": 200,
  "expectedResponse": "{ \"status\": \"ok\" }",
  "retries": 3,
  "type": "PAYMENT",
  "headers": {
    "Authorization": ["Bearer abc123"],
    "Content-Type": ["application/json"]
  },
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Pole id z odpowiedzi to identyfikator webhooka (webhookId), którego użyjesz w kroku 2.

Odpowiedź zawiera signingSecret - sekret do weryfikacji podpisu żądań przychodzących od Paymove. Zapisz go bezpiecznie po stronie swojego systemu i nie udostępniaj publicznie.

Krok 2: Przypisanie webhooka do sklepu

Webhook zacznie działać dopiero po powiązaniu z produktem. W URL podmień webhookId (z kroku 1) oraz productId swojego sklepu.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/6b23ecd9-14c8-47fc-add0-b71ec50e9d66/products/891412c8-8717-4449-9543-e34112bec470 \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Odpowiedź (200): obiekt webhooka (taki sam jak w kroku 1), potwierdzający powiązanie. Od tego momentu każda opłacona płatność w tym sklepie wywołuje Twój endpoint.

Weryfikacja konfiguracji

Listę produktów powiązanych z webhookiem sprawdzisz wywołaniem:

curl --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/6b23ecd9-14c8-47fc-add0-b71ec50e9d66/products \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Odpowiedź (200): tablica produktów powiązanych z webhookiem:

[
  {
    "id": "891412c8-8717-4449-9543-e34112bec470",
    "name": "Sklep Testowy",
    "productType": "PAY",
    "status": "ACTIVE"
  }
]

Jak wygląda powiadomienie o płatności?

Po zakończonej płatności Paymove wysyła na Twój endpoint żądanie zgodne z requestTemplate i skonfigurowanymi headers. Dla szablonu z kroku 1 body wygląda tak:

{
  "orderId": "order-123",
  "price": 1000
}

orderId to externalId, który przekazałeś tworząc płatność - dzięki temu jednoznacznie dopasujesz powiadomienie do zamówienia w swoim systemie.

Powyższy kształt to wynik requestTemplate. Gdyby szablon był pusty, Paymove wysłałby pełny obiekt płatności - zestaw pól opisuje Konfiguracja.

Zanim zaufasz treści powiadomienia, zweryfikuj nagłówek X-Paymove-Signature. Bez tego dowolna osoba znająca Twój endpoint może wysłać spreparowane powiadomienie i uzyskać realizację zamówienia bez płatności. Gotowy kod: Weryfikacja podpisu webhooka.

Twój system powinien odpowiedzieć kodem dokładnie równym expectedCode (zwyczajowo 200 i body { "status": "ok" }, choć treść odpowiedzi nie jest sprawdzana) - dopiero wtedy Paymove uznaje doręczenie za udane. Odpowiedź 201 czy 204 przy expectedCode: 200 liczy się jako niepowodzenie i nie jest ponawiana. Doręczenie zakończone kodem 4xx, 5xx lub błędem sieci zostanie ponowione tyle razy, ile wskazuje retries - domyślnie 0, czyli ani razu.

Realizuj zamówienie po otrzymaniu webhooka, a nie po powrocie klienta na returnUrl - klient może zamknąć przeglądarkę zanim wróci do Twojego sklepu, a samo przekierowanie można wywołać bez opłacenia płatności.

Wprowadzenie

Integracje

Tutoriale

Pomoc

Krok 1: Rejestracja webhooka

Krok 2: Przypisanie webhooka do sklepu

Weryfikacja konfiguracji

Jak wygląda powiadomienie o płatności?

Co dalej?

Bramka płatnicza: podstawowa integracja

Webhooki

​Krok 1: Rejestracja webhooka

​Krok 2: Przypisanie webhooka do sklepu

​Weryfikacja konfiguracji

​Jak wygląda powiadomienie o płatności?

​Co dalej?

Bramka płatnicza: podstawowa integracja

Webhooki

Krok 1: Rejestracja webhooka

Krok 2: Przypisanie webhooka do sklepu

Weryfikacja konfiguracji

Jak wygląda powiadomienie o płatności?

Co dalej?