REST API

Dokumentacja endpointów PAY API (DocPay): produkt, subprodukt i kody QR, cennik, formularze, personalizacja UI oraz webhooki. Podstawowy scenariusz integracji (produkt + subprodukt) opisany jest w Tutorialu.

1. Produkt

Produkt reprezentuje Twoją usługę w systemie Paymove i jest rootem całego modelu - subprodukty, cennik, formularze, customizacje i webhooki są podłączane do konkretnego produktu. Produkt tworzysz jednorazowo.

Endpointy - Produkt

Metoda	Endpoint	Opis
POST	`/api/product/pay`	Tworzy produkt.
PATCH	`/api/product/pay/{productId}`	Aktualizuje produkt.

Utworzenie produktu

POST /api/product/pay

{
  "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
  "productType": "PAY",
  "name": "Testowy Produkt",
  "shortName": "3456",
  "location": "Warszawa",
  "timezone": "Europe/Warsaw"
}

Pole	Opis
`partnerId`	Identyfikator partnera (nadawany przez Paymove).
`productType`	Typ produktu - dla DocPay: `PAY`.
`name`	Nazwa produktu.
`shortName`	Krótka nazwa wyświetlana.
`location`	Lokalizacja (np. miasto).
`timezone`	Strefa czasowa IANA (np. `Europe/Warsaw`).
`bankAccountDetails.iban`	Opcjonalnie - IBAN rachunku do wypłat dla płatności tego produktu (`PL` i 26 cyfr, bez spacji). Subprodukt może go nadpisać - przykład.
`bankAccountDetails.holderName`	Opcjonalnie - nazwa posiadacza rachunku.
`bankAccountDetails.nip`	Opcjonalnie - NIP posiadacza rachunku.

Odpowiedź (200):

{
  "id": "d0a834f9-94a4-4b3a-aa10-27d911e3633f",
  "name": "Testowy Produkt",
  "location": "Warszawa",
  "partner": {
    "id": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "name": "Nazwa Partnera Sp. z o.o.",
    "productTypes": ["PAY"]
  },
  "timezone": "Europe/Warsaw",
  "shortName": "3456",
  "emailEnabled": true,
  "smsEnabled": false,
  "fee": {
    "id": "01f9754e-78e3-4b2c-8186-d6862598a95a",
    "minimum": 30,
    "amount": 5,
    "fixed": false
  },
  "productType": "PAY",
  "status": "ACTIVE",
  "creator": "PAYMOVE",
  "reviewEnabled": false,
  "createdAt": 1783245692.623763835,
  "updatedAt": 1783245692.623763835
}

Pole id to identyfikator produktu (productId) używany w pozostałych endpointach.

Aktualizacja produktu

PATCH /api/product/pay/{productId}

Możesz wysłać tylko pola do zmiany; pozostałe relacje (cennik, formularze, webhooki) pozostają bez zmian. Rachunku do wypłat nie zmienisz tym wywołaniem - ustawisz go wyłącznie przy tworzeniu produktu.

Rachunek do wypłat (IBAN)

Przy tworzeniu produktu możesz od razu wskazać rachunek, na który Paymove wypłaci środki z płatności tego produktu. Dodaj do body obiekt bankAccountDetails:

POST /api/product/pay

{
  "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
  "productType": "PAY",
  "name": "Testowy Produkt",
  "shortName": "3456",
  "location": "Warszawa",
  "timezone": "Europe/Warsaw",
  "bankAccountDetails": {
    "iban": "PL61109010140000071219812874",
    "holderName": "Nazwa Partnera Sp. z o.o.",
    "nip": "1234567890"
  }
}

Odpowiedź zawiera wtedy dodatkowo pole bankAccountId - identyfikator rachunku zapisanego na Twoim koncie partnera.

Wymagany jest tylko iban - w pełnej postaci: PL i 26 cyfr, wielkimi literami, bez spacji. Suma kontrolna jest weryfikowana, a nieprawidłowy IBAN kończy się kodem 400.

To nie jest rachunek, na który płaci klient. bankAccountDetails decyduje wyłącznie o tym, dokąd trafią wypłacone środki.

2. Subprodukt i kody QR

Subprodukt reprezentuje pojedynczą płatność (np. wezwanie do zapłaty, bilet) powiązaną z zewnętrznym identyfikatorem (externalId). W odpowiedzi generowany jest kod QR w wybranym formacie (PNG/SVG). Po zeskanowaniu kodu użytkownik trafia do płatności za dany subprodukt.

Dane wejściowe

Pole	Opis
`externalId`	Identyfikator dokumentu w Twoim systemie. Wyświetlany w panelu Paymove jako numer dokumentu.
`imageFormat`	Format grafiki kodu QR: `svg` lub `png`.
`bannerType`	Typ banera/karty (np. `ticket`) - wpływa na prezentację/układ.
`price`	Kwota w groszach (np. `25000` = 250,00 PLN).
`details`	Pary klucz-wartość wyświetlane klientowi na stronie płatności (np. `"Nr. dokumentu": "..."`).
`bankAccountDetails`	Opcjonalnie - rachunek do wypłaty środków z płatności za ten subprodukt (`iban`, `holderName`, `nip`). Nadpisuje rachunek produktu; przy powtórzonym `externalId` jest ignorowany. Szczegóły: Rachunek do wypłaty subproduktu.

Endpoint - Subprodukt

Metoda	Endpoint	Opis
POST	`/api/pay/product/{productId}/subproduct`	Rejestruje subprodukt na podstawie `externalId` i generuje kod QR. Po rejestracji użytkownik może opłacić subprodukt po zeskanowaniu kodu.

Rejestracja subproduktu

POST /api/pay/product/{productId}/subproduct

{
  "externalId": "test-external#2",
  "imageFormat": "svg",
  "bannerType": "ticket",
  "price": 25000,
  "details": {
    "Nr. dokumentu": "test-external#2"
  }
}

Odpowiedź (200) to binarna zawartość obrazka z kodem QR w formacie wskazanym w imageFormat (Content-Type: application/octet-stream) - zapisz body odpowiedzi bezpośrednio do pliku. Grafika to gotowy do druku baner z kodem QR przekierowującym do płatności za ten subprodukt.

Rachunek do wypłaty subproduktu

Subprodukt może mieć własny rachunek do wypłat - np. gdy płatności za różne dokumenty mają trafiać na różne konta. Rachunek subproduktu nadpisuje rachunek produktu; bez niego obowiązuje rachunek produktu.

POST /api/pay/product/{productId}/subproduct

{
  "externalId": "test-external#3",
  "imageFormat": "svg",
  "bannerType": "ticket",
  "price": 25000,
  "details": {
    "Nr. dokumentu": "test-external#3"
  },
  "bankAccountDetails": {
    "iban": "PL61109010140000071219812874",
    "holderName": "Nazwa Partnera Sp. z o.o.",
    "nip": "1234567890"
  }
}

IBAN podlega tym samym zasadom co przy produkcie: pełna postać bez spacji, weryfikowana suma kontrolna, nieprawidłowy kończy się kodem 400 i subprodukt nie powstaje.
Gdy rachunek o tym IBAN-ie już istnieje, a podasz inne holderName lub nip, dane tego rachunku zostaną zaktualizowane.
Przy powtórzonym externalId Paymove zwraca istniejący subprodukt, a bankAccountDetails jest ignorowany - rachunku zarejestrowanego subproduktu nie zmienisz.

3. Cennik

Cennik definiuje opcje płatności dostępne dla klienta - np. „1 godzina”, „cały dzień”, „bilet weekendowy”. Każda pozycja (pricing entry) to oddzielna opcja zakupu wyświetlana na stronie produktu.

Dane pozycji cenowej

Pole	Opis
`price`	Wartość w groszach (np. 150 = 1,50 PLN).
`description`	Opis słowny opcji (np. „1 godzina parkowania”).
`details`	Dodatkowe dane pozycji - dowolne pary klucz-wartość jako obiekt JSON.

Endpointy - Cennik

Metoda	Endpoint	Opis
GET	`/api/pay/products/{productId}/pricing/entries`	Zwraca wszystkie pozycje cenowe dla produktu.
POST	`/api/pay/products/{productId}/pricing/entries`	Tworzy nową pozycję cenową.
PATCH	`/api/pay/products/{productId}/pricing/entries/{entryId}`	Aktualizuje pozycję cenową.
DELETE	`/api/pay/products/{productId}/pricing/entries/{entryId}`	Usuwa pozycję cenową. Po usunięciu wariant nie jest dostępny przy zakupie.

Utworzenie pozycji cennika

POST /api/pay/products/{productId}/pricing/entries

{
  "price": 150,
  "description": "1 godzina parkowania",
  "details": { "vat": 23, "unit": "godzina" }
}

Aktualizacja pozycji cennika

PATCH /api/pay/products/{productId}/pricing/entries/{entryId}

{
  "price": 150000000,
  "details": { "vat": 23, "unit": "godzina" }
}

Zmiana jest natychmiast widoczna dla klientów wybierających daną opcję.

4. Formularze

Formularze służą do zbierania od klientów danych wymaganych do zakupu - np. e-mail, numer rejestracyjny, dane kontaktowe. Formularze są wersjonowane; każda zmiana (dodanie/edycja/usunięcie pola) tworzy nową wersję. Bieżąca wersja oznaczana jest flagą isCurrent.

Dane pola formularza (Field)

Pole	Opis
`name`	Nazwa pola (np. `email`).
`type`	Typ: `TEXT`, `NUMBER`, `SELECT`, `EMAIL` itd.
`labels`	Etykiety językowe (np. `pl`, `en`).
`validators`	Walidacje: `required`, `pattern`, `maxLength` itd.

Endpointy - Formularze

Metoda	Endpoint	Opis
GET	`/api/pay/product/{productId}/form`	Lista formularzy dla produktów PAY.
GET	`/api/pay/product/{productId}/form/{formId}`	Szczegóły formularza (pola, wersja, isCurrent).
POST	`/api/pay/product/{productId}/form`	Tworzy formularz przypisany do produktu.
DELETE	`/api/pay/product/{productId}/form/{formId}`	Usuwa formularz. Nie wpływa na dane z już zrealizowanych zakupów.

Endpointy - Pola (Fields)

Metoda	Endpoint	Opis
GET	`/api/pay/product/{productId}/form/field/{fieldId}`	Szczegóły pola.
POST	`/api/pay/product/{productId}/form/{formId}/fields`	Dodaje pole - tworzy nową wersję formularza, nowa wersja staje się bieżąca.
PATCH	`/api/pay/product/{productId}/form/{formId}/field/{fieldId}`	Aktualizuje pole - tworzy nową wersję formularza z zaktualizowanym polem.
DELETE	`/api/pay/product/{productId}/form/{formId}/field/{fieldId}`	Usuwa pole - tworzy nową wersję bez tego pola.

Utworzenie formularza

POST /api/pay/product/{productId}/form

{
  "fields": [],
  "version": 1,
  "isCurrent": true
}

Dodanie pola (np. e-mail)

POST /api/pay/product/{productId}/form/{formId}/fields

{
  "name": "email",
  "type": "TEXT",
  "labels": {
    "en": "Email",
    "pl": "Adres e-mail"
  },
  "validators": {
    "required": true,
    "maxLength": 100,
    "pattern": "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$"
  }
}

Operacja automatycznie tworzy nową wersję formularza; poprzednia traci status bieżącej (isCurrent).

5. Personalizacja UI

Customization pozwala zmienić wygląd i treści widoczne na stronie zakupu produktu. Wszystkie teksty (tytuły, przyciski, opisy) są konfigurowane z poziomu API - frontend jest w pełni sterowany przez partnera bez zmian w kodzie.

Parametry customizacji - co modyfikują

Parametr	Co modyfikuje	Gdzie się wyświetla
`title`	Główny tytuł strony/productu.	Nagłówek na górze widoku zakupu.
`subtitle`	Tekst pod tytułem.	Bezpośrednio pod tytułem (subtytuł).
`buttonText`	Tekst przycisku akcji (np. „Kup teraz”, „Zapłać”).	Przycisk potwierdzenia na stronie płatności.
`summaryHeader`	Nagłówek sekcji podsumowania.	Nagłówek bloku z podsumowaniem zamówienia przed płatnością.
`summaryFirstLine`	Pierwsza linia w sekcji podsumowania.	Tekst w podsumowaniu (np. opis kwoty lub produktu).
`summarySecondLine`	Druga linia w sekcji podsumowania.	Kolejna linia w podsumowaniu.
`cardDescription`	Opis karty produktu.	Opis wyświetlany na karcie/listingu produktu (np. w wyborze produktu lub w podglądzie).
`locale`	Język/wersja językowa (np. `pl-PL`, `en-GB`).	Określa, która wersja tekstów (dla danej customizacji) jest używana; pozwala mieć wiele customizacji (np. osobno PL i EN).

Dla jednego produktu możesz mieć wiele customizacji z różnymi locale; system wybiera odpowiednią według ustawień użytkownika lub kontekstu.

Endpointy - Personalizacja

Metoda	Endpoint	Opis
GET	`/api/pay/product/{productId}/customization`	Lista wszystkich customizacji.
GET	`/api/pay/product/{productId}/customization/{id}`	Szczegóły customizacji (wszystkie pola).
POST	`/api/pay/product/{productId}/customization`	Tworzy customizację dla produktu.
PATCH	`/api/pay/product/{productId}/customization/{id}`	Aktualizuje customizację (dowolne pola). Zmiana jest od razu widoczna na froncie.
DELETE	`/api/pay/product/{productId}/customization/{id}`	Usuwa customizację. Produkt przestaje używać tej konfiguracji; inne customizacje i usługi nie są zmieniane.

Utworzenie customizacji

POST /api/pay/product/{productId}/customization

{
  "title": "Nowy produkt",
  "subtitle": "Subtytuł",
  "summaryHeader": "Nagłówek podsumowania",
  "summaryFirstLine": "Pierwsza linia",
  "summarySecondLine": "Druga linia",
  "buttonText": "Kup teraz",
  "cardDescription": "Opis karty",
  "locale": "pl-PL"
}

Aktualizacja customizacji

PATCH /api/pay/product/{productId}/customization/{id}

Możesz wysłać tylko te pola, które chcesz zmienić, np.:

{
  "summaryFirstLine": "Pierwsza linia",
  "summarySecondLine": "Druga linia",
  "buttonText": "Kup teraz",
  "cardDescription": "Opis karty",
  "locale": "pl-PL"
}

Zmiana jest natychmiast odzwierciedlana w prezentacji produktu na stronie zakupu.

6. Webhooki

Webhooki służą do automatycznego informowania partnera o zakończonej płatności lub do pobrania cennika z systemu zewnętrznego. Po zarejestrowaniu webhooka należy przypisać go do produktu - wtedy zdarzenia związane z tym produktem są wysyłane na wskazany endpoint.

Pola konfiguracji webhooka

Pole	Opis
`endpoint`	URL, na który Paymove wysyła żądanie (POST).
`method`	Metoda HTTP (np. `POST`).
`headers`	Nagłówki dołączane do żądania (np. `Authorization`, `Content-Type`).
`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.
`type`	Typ zdarzenia (np. `PAYMENT`).

Endpointy - Webhooki

Metoda	Endpoint	Opis
GET	`/api/pay/plugin/webhook`	Lista webhooków. Opcjonalne query: `productId`.
GET	`/api/pay/plugin/webhook/{webhookId}`	Szczegóły webhooka.
GET	`/api/pay/plugin/webhook/{webhookId}/products`	Lista produktów powiązanych z webhookiem.
POST	`/api/pay/plugin/webhook`	Tworzy webhook.
POST	`/api/pay/plugin/webhook/{webhookId}/products/{productId}`	Przypisuje webhook do produktu.
PATCH	`/api/pay/plugin/webhook/{webhookId}`	Aktualizuje webhook. Wpływa na wszystkie powiązane produkty.

Utworzenie webhooka

POST /api/pay/plugin/webhook

{
  "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": "6909ca83-410f-47c4-910d-2057f8565a8c",
  "type": "PAYMENT",
  "headers": {
    "Authorization": ["Bearer abc123"],
    "Content-Type": ["application/json"]
  }
}

Odpowiedź (200): obiekt webhooka z nadanym id (identyfikator webhooka) oraz polem signingSecret:

{
  "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"
}

signingSecret służy do weryfikacji podpisu żądań przychodzących od Paymove. Przechowuj go bezpiecznie.

Po utworzeniu wywołaj POST /api/pay/plugin/webhook/{webhookId}/products/{productId}, aby powiązać webhook z produktem (odpowiedź: obiekt webhooka). Od tego momentu zdarzenia (np. udana płatność) dla tego produktu trafiają na Twój endpoint.

Wprowadzenie

Integracje

Tutoriale

Pomoc

1. Produkt

Endpointy - Produkt

Utworzenie produktu

Aktualizacja produktu

Rachunek do wypłat (IBAN)

2. Subprodukt i kody QR

Dane wejściowe

Endpoint - Subprodukt

Rejestracja subproduktu

Rachunek do wypłaty subproduktu

3. Cennik

Dane pozycji cenowej

Endpointy - Cennik

Utworzenie pozycji cennika

Aktualizacja pozycji cennika

4. Formularze

Dane pola formularza (Field)

Endpointy - Formularze

Endpointy - Pola (Fields)

Utworzenie formularza

Dodanie pola (np. e-mail)

5. Personalizacja UI

Parametry customizacji - co modyfikują

Endpointy - Personalizacja

Utworzenie customizacji

Aktualizacja customizacji

6. Webhooki

Pola konfiguracji webhooka

Endpointy - Webhooki

Utworzenie webhooka

​1. Produkt

​Endpointy - Produkt

​Utworzenie produktu

​Aktualizacja produktu

​Rachunek do wypłat (IBAN)

​2. Subprodukt i kody QR

​Dane wejściowe

​Endpoint - Subprodukt

​Rejestracja subproduktu

​Rachunek do wypłaty subproduktu

​3. Cennik

​Dane pozycji cenowej

​Endpointy - Cennik

​Utworzenie pozycji cennika

​Aktualizacja pozycji cennika

​4. Formularze

​Dane pola formularza (Field)

​Endpointy - Formularze

​Endpointy - Pola (Fields)

​Utworzenie formularza

​Dodanie pola (np. e-mail)

​5. Personalizacja UI

​Parametry customizacji - co modyfikują

​Endpointy - Personalizacja

​Utworzenie customizacji

​Aktualizacja customizacji

​6. Webhooki

​Pola konfiguracji webhooka

​Endpointy - Webhooki

​Utworzenie webhooka

1. Produkt

Endpointy - Produkt

Utworzenie produktu

Aktualizacja produktu

Rachunek do wypłat (IBAN)

2. Subprodukt i kody QR

Dane wejściowe

Endpoint - Subprodukt

Rejestracja subproduktu

Rachunek do wypłaty subproduktu

3. Cennik

Dane pozycji cenowej

Endpointy - Cennik

Utworzenie pozycji cennika

Aktualizacja pozycji cennika

4. Formularze

Dane pola formularza (Field)

Endpointy - Formularze

Endpointy - Pola (Fields)

Utworzenie formularza

Dodanie pola (np. e-mail)

5. Personalizacja UI

Parametry customizacji - co modyfikują

Endpointy - Personalizacja

Utworzenie customizacji

Aktualizacja customizacji

6. Webhooki

Pola konfiguracji webhooka

Endpointy - Webhooki

Utworzenie webhooka