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.

Pracujesz z agentem AI? Kroki 1-3 wykona za Ciebie - wystarczy klucz API i partnerId, o nazwę sklepu i resztę pól zapyta sam. Zobacz Integrację z agentami AI.

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",
  "metadata": {
    "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`	Opcjonalnie - własny UUID produktu. Pominięty zostanie nadany przez Paymove; UUID, który już istnieje, kończy się błędem `400`
`name`	`string`	Nazwa sklepu - checkout wyświetla ją klientowi jako odbiorcę płatności (pojedyncza płatność może ją nadpisać przez `details.recipient`)
`fullName`	`string`	Opcjonalnie - pełna nazwa firmy. Trafia do domyślnego payloadu webhooka
`shortName`	`string`	Opcjonalnie - krótka nazwa wyświetlana
`location`	`string`	Lokalizacja - dowolny tekst, np. miasto albo kod kraju. Nie jest wyświetlana klientowi
`timezone`	`string`	Strefa czasowa IANA (np. `Europe/Warsaw`)
`metadata.locale`	`string`	Opcjonalnie - domyślny język checkoutu (np. `pl-PL`)
`metadata.logoUrl`	`string`	Opcjonalnie - publiczny adres HTTPS logo sklepu. Checkout pokazuje je obok nazwy sprzedawcy jako kwadrat 34×34 px (obraz jest przycinany do kwadratu); gdy nie da się go załadować, wyświetla domyślną ikonę
`metadata.merchantDomain`	`string`	Opcjonalnie - domena Twojego sklepu (np. `sklep.example.com`). Wymagana wyłącznie dla Apple Pay przy checkoucie w modalu
`bankAccountDetails.iban`	`string`	Opcjonalnie - IBAN rachunku do wypłat dla płatności tego produktu (`PL` i 26 cyfr, bez spacji). Pojedyncza płatność może go nadpisać - zobacz Rachunek do wypłaty. Ustawisz go wyłącznie przy tworzeniu produktu
`bankAccountDetails.holderName`	`string`	Opcjonalnie - nazwa posiadacza rachunku
`bankAccountDetails.nip`	`string`	Opcjonalnie - NIP posiadacza rachunku

2. Rejestracja webhooka

Webhook to adres URL po Twojej stronie, który Paymove wywołuje po zakończonej 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 wysyłanego na Twój endpoint. Pole jest wymagane - to ono decyduje, jakie dane otrzymasz. Zmienne podstawiane są w formacie `{{nazwa}}`, np. `{{externalId}}`, `{{price}}`, `{{status}}` - pełna lista w Payloadzie webhooka
`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

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

Payload webhooka

Kształt payloadu zależy od tego, czy ustawiłeś requestTemplate. Bez requestTemplate Paymove wysyła pełny obiekt płatności. Pola bez wartości są pomijane, więc konkretne powiadomienie może zawierać ich mniej:

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

Z requestTemplate payload to dokładnie to, co wyrenderuje Twój szablon - ani mniej, ani więcej. 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)

W szablonie możesz użyć każdego pola domyślnego payloadu:

Zmienna	Opis
`{{externalId}}`	Twój identyfikator zamówienia - po nim dopasujesz płatność
`{{orderId}}`	Identyfikator zamówienia po stronie Paymove
`{{price}}`	Kwota w groszach - ta sama, którą podałeś przy tworzeniu płatności
`{{status}}`	Status płatności
`{{paymentMethod}}`	Użyta metoda płatności
`{{email}}`	Adres e-mail klienta, jeśli był znany
`{{date}}`	Czas utworzenia płatności (epoka uniksowa)
`{{activeFrom}}`	Czas utworzenia zamówienia (epoka uniksowa)
`{{requestId}}`	Identyfikator żądania, przydatny przy zgłoszeniach do wsparcia
`{{nip}}`	NIP, jeśli został przekazany przy płatności
`{{id}}`, `{{name}}`, `{{fullName}}`, `{{shortName}}`, `{{location}}`	Dane produktu z jego konfiguracji

Wartości podstawiane w szablonie tekstowym trafiają do payloadu jako łańcuchy znaków - "price": "{{price}}" da "1000", a nie 1000. Zmienna bez wartości renderuje się jako pusty tekst.

Payload zawiera wyłącznie pola wypisane w szablonie. Jeśli chcesz rozróżniać statusy płatności, dodaj do niego {{status}} - inaczej Twój endpoint nie odróżni powiadomień.

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