Konfiguracja

Integracja z bramką płatniczą Paymove składa się z czterech kroków: tworzysz produkt, rejestrujesz webhook, przypisujesz go do produktu, a następnie tworzysz płatności przez SDK lub REST API.

1. Utworzenie produktu

Produkt reprezentuje Twój sklep w systemie Paymove. Wszystkie płatności i subprodukty są tworzone w ramach tego produktu. Przykładowy request tworzenia produktu:

POST https://gateway-api.sandbox.paymove.io/api/product/pay

{
  "partnerId": "{{partnerId}}",
  "productType": "PAY",
  "id": "2f6c19e8-84a7-4f50-b950-8d5a05e0bbf2",
  "name": "MerchantShop",
  "fullName": "Merchant Shop Sp. z o.o.",
  "shortName": "MShop",
  "location": "PL",
  "timezone": "Europe/Warsaw",
  "productMetadata": {
    "locale": "pl-PL"
  }
}

Pole	Typ	Opis
`partnerId`	`uuid`	Identyfikator partnera (wewnętrzny, nadawany przez Paymove)
`productType`	`enum`	Typ produktu - `PAY` dla bramki płatniczej
`id`	`uuid`	UUID produktu
`name`	`string`	Nazwa skrócona produktu
`fullName`	`string`	Pełna nazwa firmy
`shortName`	`string`	Nazwa wyświetlana
`location`	`string`	Lokalizacja (kod kraju)
`timezone`	`string`	Strefa czasowa IANA (np. `Europe/Warsaw`)
`productMetadata.locale`	`string`	Opcjonalnie - domyślny język checkoutu (np. `pl-PL`)

2. Rejestracja webhooka

Webhook to adres URL po Twojej stronie, który Paymove wywołuje po każdej zmianie statusu płatności. Dzięki temu nie musisz ręcznie sprawdzać statusu - zamówienia mogą być realizowane automatycznie. Lista możliwych statusów: tabela statusów. Przykładowy request rejestracji webhooka:

POST https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook

{
  "name": "PaymentSuccessHook",
  "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": "{{partnerId}}",
  "type": "PAYMENT",
  "headers": {
    "Content-Type": ["application/json"]
  }
}

Pole	Typ	Opis
`name`	`string`	Nazwa webhooka
`endpoint`	`string`	URL, na który Paymove wyśle powiadomienie po udanej płatności
`method`	`enum`	Metoda HTTP (`POST`)
`requestTemplate`	`object`	Szablon payloadu - podstawiane są zmienne odpowiadające polom domyślnego payloadu, m.in. `{{externalId}}`, `{{price}}`, `{{status}}`, `{{paymentMethod}}`
`responseTemplate`	`object`	Oczekiwana struktura odpowiedzi od merchanta
`expectedCode`	`integer`	Oczekiwany kod HTTP odpowiedzi (`200`). Pole jest wymagane - jego pominięcie kończy się błędem `500`
`expectedResponse`	`string`	Oczekiwana odpowiedź jako string JSON. Zapisywana przy webhooku, ale nieporównywana z faktyczną odpowiedzią
`retries`	`integer`	Liczba ponownych prób przy niepowodzeniu. Pole jest wymagane - jego pominięcie kończy się błędem `500`. Wartość `0` oznacza brak ponawiania
`partnerId`	`uuid`	Identyfikator partnera (wewnętrzny)
`type`	`enum`	Typ zdarzenia (`PAYMENT`)
`headers`	`object`	Nagłówki HTTP dołączane do webhooka

Jak działa webhook

Domyślnie webhook jest wysyłany wyłącznie dla statusu COMPLETED. Powiadomienia o pozostałych statusach (CANCELED, ERROR, REFUNDED) wymagają włączenia po stronie Paymove dla konkretnego produktu - napisz na integration@paymove.io.

Statusy płatności w Paymove:

Status	Znaczenie
`INITIALIZED`	Płatność utworzona, klient jeszcze nie zapłacił
`PENDING`	Płatność w toku po stronie operatora
`COMPLETED`	Płatność zakończona sukcesem - realizuj zamówienie
`CANCELED`	Klient anulował płatność
`ERROR`	Płatność nie powiodła się
`REFUNDED`	Płatność zwrócona
`WAITING_FOR_EXTERNAL_ACTION`	Stan przejściowy wewnątrz Paymove - nie jest stanem końcowym

Status jest zawsze przesyłany jako łańcuch znaków (np. "COMPLETED"). Liczby spotykane w starszych integracjach są wewnętrzną reprezentacją bazodanową i nie pojawiają się w API ani w webhookach.

Payload webhooka

Kształt payloadu zależy od tego, czy ustawiłeś requestTemplate. Bez requestTemplate Paymove wysyła pełny obiekt (pola puste są pomijane):

{
  "id": "891412c8-8717-4449-9543-e34112bec470",
  "name": "MerchantShop",
  "fullName": "Merchant Shop Sp. z o.o.",
  "shortName": "MShop",
  "location": "PL",
  "externalId": "order-123",
  "orderId": "PAY1784798914400",
  "price": 950,
  "status": "COMPLETED",
  "paymentMethod": "BLIK",
  "email": "klient@example.com",
  "date": 1783246791.745352526,
  "requestId": "8f2b1c44-0d7e-4a91-b2c3-5e7f9a1d3c60"
}

W domyślnym payloadzie price to kwota pomniejszona o prowizję Paymove, a nie kwota pobrana od klienta. Jeśli weryfikujesz zgodność kwoty, porównuj ją z wartością zapisaną u siebie przy tworzeniu płatności, a nie z tym polem.

Z requestTemplate payload to dokładnie to, co wyrenderuje Twój szablon. Dla szablonu z punktu 2:

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

Pole	Typ	Opis
`orderId`	`string`	Wartość `{{externalId}}` - Twój identyfikator zamówienia
`price`	`string`	Wartość `{{price}}` - kwota w groszach (jako string)

Weryfikacja podpisu

Każde żądanie webhooka zawiera nagłówek X-Paymove-Signature. Zweryfikuj go, zanim zaufasz treści - bez tego każdy, kto zna Twój URL, może podszyć się pod Paymove i zrealizować zamówienie bez płatności. Gotowy kod w Node.js, Pythonie i Javie: Weryfikacja podpisu webhooka.

Wymagana odpowiedź

Twój serwer musi odpowiedzieć kodem HTTP równym expectedCode. Przyjęło się zwracać przy tym:

{ "status": "ok" }

O powodzeniu doręczenia decyduje wyłącznie kod HTTP, i musi być dokładnie równy expectedCode. Przy domyślnym 200 odpowiedź 201 lub 204 jest traktowana jako niepowodzenie - i, co gorsza, nie jest ponawiana: harmonogram ponowień uruchamiają tylko kody 4xx, 5xx i błędy sieci. Zły kod z rodziny 2xx bezpowrotnie gubi powiadomienie.

Treść odpowiedzi nie jest w ogóle sprawdzana. Pole expectedResponse jest zapisywane przy webhooku i zwracane w odpowiedzi API, ale nigdy nie jest porównywane z tym, co zwróci Twój serwer - możesz odesłać dowolne body.

Jeśli doręczenie się nie powiedzie, webhook zostanie ponowiony tyle razy, ile wskazuje retries - domyślnie 0, czyli ani razu. Przy ustawionym retries kolejne próby następują po 1 s, 5 s, 5 min, 1 h, a następnie co 3 h.

Wywołania webhooka nie mają limitu czasu po stronie Paymove. Odpowiadaj natychmiast, a właściwe przetwarzanie zamówienia wykonuj asynchronicznie - inaczej wolny endpoint będzie blokował przetwarzanie.

3. Przypisanie webhooka do produktu

Po utworzeniu produktu i zarejestrowaniu webhooka należy je ze sobą powiązać. Dzięki temu każde zdarzenie płatności dotyczące tego produktu automatycznie trafia pod wskazany URL webhooka. Przykładowy request:

POST https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/{webhookId}/products/{productId}

Parametr	Typ	Opis
`webhookId`	`uuid`	Identyfikator webhooka otrzymany w punkcie 2
`productId`	`uuid`	UUID produktu utworzonego w punkcie 1

4. Tworzenie płatności

Po skonfigurowaniu produktu i webhooka możesz zacząć tworzyć płatności. Wybierz metodę integracji:

SDK

Pakiet Node.js - zainicjalizuj klienta i wywołaj createPayment.

REST API

Bezpośrednie wywołania HTTP - działa z każdym językiem.

Wprowadzenie

Integracje

Tutoriale

Pomoc

1. Utworzenie produktu

2. Rejestracja webhooka

Jak działa webhook

Payload webhooka

Weryfikacja podpisu

Wymagana odpowiedź

3. Przypisanie webhooka do produktu

4. Tworzenie płatności

SDK

REST API

​1. Utworzenie produktu

​2. Rejestracja webhooka

​Jak działa webhook

​Payload webhooka

​Weryfikacja podpisu

​Wymagana odpowiedź

​3. Przypisanie webhooka do produktu

​4. Tworzenie płatności

SDK

REST API

1. Utworzenie produktu

2. Rejestracja webhooka

Jak działa webhook

Payload webhooka

Weryfikacja podpisu

Wymagana odpowiedź

3. Przypisanie webhooka do produktu

4. Tworzenie płatności