DocPay: podstawowa integracja

Podstawowy scenariusz integracji DocPay składa się z dwóch kroków. Produkt tworzysz jednorazowo, a następnie dla każdej pojedynczej płatności (np. wezwania do zapłaty) tworzysz subprodukt. W odpowiedzi otrzymujesz kod QR, który przekierowuje klienta do strony płatności. Wszystkie żądania autoryzujesz kluczem API przekazywanym w nagłówku X-API-KEY.

Przykłady używają środowiska sandbox: https://gateway-api.sandbox.paymove.io.

Krok 1: Utworzenie produktu

Produkt reprezentuje Twoją usługę w systemie Paymove i jest kontenerem dla subproduktów. Tworzysz go tylko raz, przy starcie integracji.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/product/pay \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "partnerId": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "productType": "PAY",
    "name": "Testowy Produkt",
    "shortName": "3456",
    "location": "Warszawa",
    "timezone": "Europe/Warsaw"
  }'

Pole	Wymagane	Opis
`partnerId`	Tak	Identyfikator partnera (nadawany przez Paymove).
`productType`	Tak	Typ produktu - dla DocPay zawsze `PAY`.
`name`	Tak	Nazwa produktu.
`shortName`	Tak	Krótka nazwa wyświetlana.
`location`	Tak	Lokalizacja (np. miasto).
`timezone`	Tak	Strefa czasowa IANA (np. `Europe/Warsaw`).

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 z odpowiedzi to identyfikator produktu (productId), którego użyjesz w kroku 2.

Krok 2: Utworzenie subproduktu

Subprodukt reprezentuje pojedynczą płatność - np. jedno wezwanie do zapłaty. W URL podmień identyfikator produktu (productId) otrzymany w kroku 1.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/product/1c32c81e-8f0e-40e1-8ad0-f5eeef9e3503/subproduct \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "externalId": "test-external#2",
    "imageFormat": "svg",
    "bannerType": "ticket",
    "price": 25000,
    "details": {
      "Nr. dokumentu": "test-external#2"
    }
  }'

Pole	Wymagane	Opis
`externalId`	Tak	Identyfikator dokumentu w Twoim systemie. Wyświetlany w panelu Paymove jako numer dokumentu.
`imageFormat`	Tak	Format grafiki kodu QR: `svg` lub `png`.
`bannerType`	Tak	Typ banera/karty (np. `ticket`) - wpływa na prezentację.
`price`	Tak	Kwota w groszach (np. `25000` = 250,00 PLN).
`details`	Nie	Pary klucz-wartość wyświetlane klientowi na stronie płatności (np. `"Nr. dokumentu": "..."`).

Wartości z details są wyświetlane użytkownikowi wizualnie na stronie płatności - klucz to etykieta, a wartość to prezentowany tekst.

Odpowiedź: kod QR

Odpowiedź (200) to binarna zawartość obrazka z kodem QR w formacie wskazanym w imageFormat (SVG lub PNG), zwracana z nagłówkiem Content-Type: application/octet-stream. To nie jest JSON - zapisz body odpowiedzi bezpośrednio do pliku, np.:

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/product/{productId}/subproduct \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{ ... }' \
  --output kod-qr.svg

Grafika zawiera gotowy do druku baner z kodem QR przekierowującym do płatności (dla png np. 300x780 px). Umieść go np. na wezwaniu do zapłaty - klient po zeskanowaniu trafi bezpośrednio do opłacenia dokumentu.

Co dalej?

REST API

Pełna dokumentacja endpointów: cennik, formularze, personalizacja UI i webhooki (powiadomienia o wpłacie).

Wprowadzenie

Integracje

Tutoriale

Pomoc

Krok 1: Utworzenie produktu

Krok 2: Utworzenie subproduktu

Odpowiedź: kod QR

Co dalej?

REST API

​Krok 1: Utworzenie produktu

​Krok 2: Utworzenie subproduktu

​Odpowiedź: kod QR

​Co dalej?

REST API

Krok 1: Utworzenie produktu

Krok 2: Utworzenie subproduktu

Odpowiedź: kod QR

Co dalej?