REST API

Dokumentacja endpointów PAY API (DocPay) w kolejności konfiguracji: cennik, formularze, personalizacja UI, webhooki, subprodukt i kody QR. Produkt tworzysz w sekcji Konfiguracja (krok 1).

1. 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`	JSON z dodatkowymi danymi (np. `currency`, `vat`).

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": "{\"currency\":\"PLN\",\"vat\":23}"
}

Aktualizacja pozycji cennika

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

{
  "price": 150000000,
  "details": "{\"currency\":\"PLN\",\"vat\":23}"
}

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

2. 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).

3. 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.

4. 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/plugin/webhook`	Lista webhooków. Opcjonalne query: `productId`, `partnerId`.
GET	`/api/plugin/webhook/{webhookId}`	Szczegóły webhooka.
GET	`/api/plugin/webhook/{webhookId}/products`	Lista produktów powiązanych z webhookiem.
POST	`/api/plugin/webhook`	Tworzy webhook.
POST	`/api/plugin/webhook/{webhookId}/products/{productId}`	Przypisuje webhook do produktu.
PATCH	`/api/plugin/webhook/{webhookId}`	Aktualizuje webhook. Wpływa na wszystkie powiązane produkty.

Utworzenie webhooka

POST /api/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"]
  }
}

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

5. Subprodukt i kody QR

Subprodukt służy do powiązania produktu PAY z zewnętrznym identyfikatorem (externalId) oraz do wygenerowania kodu QR w wybranym formacie (PNG/SVG). Po zeskanowaniu kodu użytkownik trafia do płatności za wcześniej zdefiniowany subprodukt (np. bilet, wezwanie do zapłaty).

Dane wejściowe

Pole	Opis
`externalId`	Zewnętrzny identyfikator subproduktu (np. ID biletu w Twoim systemie).
`imageFormat`	Format grafiki kodu QR: `svg` lub `png`.
`bannerType`	Typ banera/karty (np. `ticket`) - wpływa na prezentację/układ.

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": "some-external-id-123",
  "imageFormat": "svg",
  "bannerType": "ticket"
}

Odpowiedź zawiera dane potrzebne do wyświetlenia lub zapisania kodu QR (np. URL do obrazka lub dane graficzne). Użytkownik skanujący kod zostanie przekierowany do płatności za ten subprodukt.

Wprowadzenie

Produkty

1. Cennik

Dane pozycji cenowej

Endpointy – Cennik

Utworzenie pozycji cennika

Aktualizacja pozycji cennika

2. Formularze

Dane pola formularza (Field)

Endpointy – Formularze

Endpointy – Pola (Fields)

Utworzenie formularza

Dodanie pola (np. e-mail)

3. Personalizacja UI

Parametry customizacji - co modyfikują

Endpointy – Personalizacja

Utworzenie customizacji

Aktualizacja customizacji

4. Webhooki

Pola konfiguracji webhooka

Endpointy – Webhooki

Utworzenie webhooka

5. Subprodukt i kody QR

Dane wejściowe

Endpoint – Subprodukt

Rejestracja subproduktu

Wprowadzenie

Produkty

​1. Cennik

​Dane pozycji cenowej

​Endpointy – Cennik

​Utworzenie pozycji cennika

​Aktualizacja pozycji cennika

​2. Formularze

​Dane pola formularza (Field)

​Endpointy – Formularze

​Endpointy – Pola (Fields)

​Utworzenie formularza

​Dodanie pola (np. e-mail)

​3. Personalizacja UI

​Parametry customizacji - co modyfikują

​Endpointy – Personalizacja

​Utworzenie customizacji

​Aktualizacja customizacji

​4. Webhooki

​Pola konfiguracji webhooka

​Endpointy – Webhooki

​Utworzenie webhooka

​5. Subprodukt i kody QR

​Dane wejściowe

​Endpoint – Subprodukt

​Rejestracja subproduktu

1. Cennik

Dane pozycji cenowej

Endpointy – Cennik

Utworzenie pozycji cennika

Aktualizacja pozycji cennika

2. Formularze

Dane pola formularza (Field)

Endpointy – Formularze

Endpointy – Pola (Fields)

Utworzenie formularza

Dodanie pola (np. e-mail)

3. Personalizacja UI

Parametry customizacji - co modyfikują

Endpointy – Personalizacja

Utworzenie customizacji

Aktualizacja customizacji

4. Webhooki

Pola konfiguracji webhooka

Endpointy – Webhooki

Utworzenie webhooka

5. Subprodukt i kody QR

Dane wejściowe

Endpoint – Subprodukt

Rejestracja subproduktu