DocPay: webhooki

Webhook automatycznie powiadamia Twój system o zakończonej płatności. Konfiguracja składa się z dwóch kroków: rejestrujesz webhook, a następnie przypisujesz go do produktu. Od tego momentu zdarzenia (np. udana płatność) dla tego produktu trafiają 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 produktu utworzonego w tutorialu DocPay: podstawowa integracja.

Krok 1: Rejestracja webhooka

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": "PaymentSuccessHook",
    "endpoint": "https://example.com/webhooks/payment-success",
    "method": "POST",
    "requestTemplate": {
      "productId": "productId",
      "event": "event"
    },
    "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.
`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": "18e19688-bdda-4843-8777-0f04d0143c77",
  "name": "PaymentSuccessHook",
  "endpoint": "https://example.com/webhooks/payment-success",
  "method": "POST",
  "requestTemplate": {
    "productId": "productId",
    "event": "event"
  },
  "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 produktu

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

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/18e19688-bdda-4843-8777-0f04d0143c77/products/d0a834f9-94a4-4b3a-aa10-27d911e3633f \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Odpowiedź (200): obiekt webhooka (taki sam jak w kroku 1), potwierdzający powiązanie. Od tego momentu zdarzenia płatności dla tego produktu są wysyłane na 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/18e19688-bdda-4843-8777-0f04d0143c77/products \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

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

[
  {
    "id": "d0a834f9-94a4-4b3a-aa10-27d911e3633f",
    "name": "Testowy Produkt",
    "productType": "PAY",
    "status": "ACTIVE"
  }
]

Jak Paymove wywołuje Twój endpoint?

Po zakończonej płatności Paymove wysyła na Twój endpoint żądanie zgodne z requestTemplate i skonfigurowanymi headers. Twój system powinien odpowiedzieć kodem expectedCode (zwyczajowo 200 i body { "status": "ok" }, choć treść odpowiedzi nie jest sprawdzana). W przypadku niepowodzenia Paymove ponowi próbę tyle razy, ile wskazuje retries.

Co dalej?

REST API

Pełna dokumentacja endpointów webhooków: lista, szczegóły, aktualizacja.

Wprowadzenie

Integracje

Tutoriale

Pomoc

Krok 1: Rejestracja webhooka

Krok 2: Przypisanie webhooka do produktu

Weryfikacja konfiguracji

Jak Paymove wywołuje Twój endpoint?

Co dalej?

REST API

​Krok 1: Rejestracja webhooka

​Krok 2: Przypisanie webhooka do produktu

​Weryfikacja konfiguracji

​Jak Paymove wywołuje Twój endpoint?

​Co dalej?

REST API

Krok 1: Rejestracja webhooka

Krok 2: Przypisanie webhooka do produktu

Weryfikacja konfiguracji

Jak Paymove wywołuje Twój endpoint?

Co dalej?