REST API

REST API pozwala tworzyć płatności w ramach głównego produktu. Każde wywołanie tworzy płatność, którą klient może opłacić poprzez otrzymany redirectUrl.

Przed rozpoczęciem integracji przez REST API upewnij się, że masz skonfigurowany produkt i webhook. Przejdź do Konfiguracja, aby wykonać wymagane kroki.

Wywołuj API wyłącznie po stronie serwera. Żądanie wysłane ze strony Twojego sklepu zostanie odrzucone - a klucz i tak nigdy nie może trafić do kodu frontendowego.

1. Endpoint

POST https://gateway-api.sandbox.paymove.io/api/pay/product/{productId}/subproduct/pricing

Środowisko	Adres bazowy
Sandbox	`https://gateway-api.sandbox.paymove.io`
Produkcja	`https://api.paymove.io`

Nagłówki

Nagłówek	Wartość
`Content-Type`	`application/json`
`X-API-KEY`	Twój klucz API - `sk_test_…` w sandboxie, `sk_live_…` na produkcji

2. Przykładowe wywołanie

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/product/891412c8-8717-4449-9543-e34112bec470/subproduct/pricing \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "price": 1000,
    "externalId": "order-123",
    "details": {
      "returnUrl": "https://merchant-shop.com/payment/success",
      "productName": "Koszulka sportowa",
      "email": "klient@example.com",
      "locale": "pl-PL",
      "triggerPayment": "BLIK",
      "qrStepEnabled": true
    }
  }'

To samo w Node.js:

const url = `https://gateway-api.sandbox.paymove.io/api/pay/product/${productId}/subproduct/pricing`;

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.PAYMOVE_API_KEY,
  },
  body: JSON.stringify({
    price: Math.round(10.0 * 100), // zawsze liczba całkowita w groszach
    externalId: "order-123",
    details: {
      returnUrl: "https://merchant-shop.com/payment/success",
      productName: "Koszulka sportowa",
      email: "klient@example.com",
      locale: "pl-PL",
      triggerPayment: "BLIK",
      qrStepEnabled: true,
    },
  }),
});

if (!response.ok) {
  const error = await response.json(); // { status, message }
  throw new Error(`Paymove ${response.status}: ${error.message}`);
}

const data = await response.json();
console.log(data.redirectUrl);

Parametry body

Pole	Typ	Wymagane	Opis
`price`	`integer`	Tak	Kwota w groszach jako liczba całkowita (`1000` = 10,00 PLN)
`externalId`	`string`	Tak	Unikalny identyfikator zamówienia po Twojej stronie
`details.returnUrl`	`string`	Tak	URL powrotu klienta po płatności
`details.productName`	`string`	Nie	Nazwa produktu widoczna na checkoucie
`details.email`	`string`	Nie	Adres e-mail klienta, uzupełniany na checkoucie
`details.locale`	`string`	Nie	Nadpisuje locale z głównego produktu (np. `pl-PL`)
`details.recipient`	`string`	Nie	Nazwa odbiorcy wyświetlana na checkoucie
`details.triggerPayment`	`enum`	Nie	Metoda płatności wybrana z góry w checkoucie (Google Pay i Apple Pay startują automatycznie)
`details.qrStepEnabled`	`boolean`	Nie	Kod QR na desktopie - klient kończy płatność na telefonie
`details.autoclose`	`integer`	Nie	Po ilu ms od udanej płatności checkout sam wraca na `details.returnUrl`. Odliczanie widać w przycisku „Wróć do sklepu”, a interakcja klienta je anuluje. W widgecie zamiast przekierowania zamyka się modal. Brak pola = bez auto-powrotu

price musi być liczbą całkowitą. Wartość z częścią dziesiętną (np. 12.99) zostanie po cichu obcięta do 12 groszy, a API i tak zwróci 200. Przeliczaj złotówki przez Math.round(kwota * 100).

Bramka rozlicza wyłącznie w PLN - w żądaniu nie ma pola waluty. Pole currency, jeśli je wyślesz, zostanie zignorowane.

details to swobodny obiekt - możesz przekazać w nim własne pola, a Paymove je zachowa. Checkout odczytuje jednak tylko: returnUrl, redirectUrl, productName, email, locale, orderId, recipient, triggerPayment, qrStepEnabled i autoclose. Pozostałe pola (np. customerId) są wyłącznie przekazywane na wylot i nigdzie się nie wyświetlają.

Nieznane pola w body są po cichu ignorowane, a API zwraca 200. Wysłanie amount zamiast price albo returnUrl na najwyższym poziomie zamiast w details nie zgłosi błędu - płatność powstanie z niekompletnymi danymi. Trzymaj się dokładnie powyższej struktury.

Odpowiedź

{
  "redirectUrl": "https://checkout.sandbox.paymove.io/891412c8-8717-4449-9543-e34112bec470?externalId=ec6RtwTZKb"
}

Pole	Typ	Opis
`redirectUrl`	`string`	Adres checkoutu - przekieruj klienta pod ten URL w celu sfinalizowania płatności

Odpowiedź ma status HTTP 200 (nie 201).

Parametr externalId w zwróconym adresie (tutaj ec6RtwTZKb) to wygenerowany przez Paymove 10-znakowy skrót płatności, a nie Twój externalId (order-123). Zapisz go u siebie - posługujesz się nim przy sprawdzaniu statusu płatności.

Błędy

Wszystkie błędy mają kształt {"status": <int>, "message": "<tekst>"}. Rozgałęziaj logikę po statusie HTTP, nigdy po treści message.

{
  "status": 401,
  "message": "Invalid API key"
}

Pełna lista: Kody błędów.

Wskazanie metody płatności

Pole details.triggerPayment z góry wybiera metodę płatności w checkoucie, dzięki czemu klient nie musi jej szukać na liście.

Wartość	Metoda
`GPAY`	Google Pay
`APAY`	Apple Pay
`BLIK`	BLIK
`CARD`	Płatność kartą
`TRANSFER`	Przelew tradycyjny
`PAY_BY_LINK`	Pay by Link
`PAYPO`	PayPo

Nieznana wartość jest pomijana - checkout zachowa się wtedy standardowo.

Automatyczny start - czyli otwarcie płatności tak, jakby klient kliknął Zapłać - dotyczy wyłącznie Google Pay i Apple Pay. Przy pozostałych pięciu metodach kafelek jest tylko zaznaczony, a klient klika Zapłać sam. Nie buduj procesu, który zakłada, że BLIK czy PayPo wystartują same.

Nawet dla portfeli auto-start wymaga, żeby checkout znał adres e-mail klienta - przekaż go w details.email. Nie zadziała też w widgecie osadzonym w modalu ani gdy metoda nie jest dostępna dla Twojego produktu. W każdym z tych przypadków metoda zostaje jedynie zaznaczona.

Auto-start działa wyłącznie przy pierwszym wyświetleniu checkoutu. Gdy klient sam wybierze metodę płatności, nie uruchomi się ponownie - aż do odświeżenia strony.

Google Pay i Apple Pay otwierają natywne okno przeglądarki, które zwykle wymaga gestu klienta - automatyczne uruchomienie może zostać przez nią zablokowane. Klient zobaczy wtedy standardowy ekran płatności i opłaci zamówienie ręcznie.

Krok z kodem QR

Pole details.qrStepEnabled włącza dodatkowy ekran startowy checkoutu na desktopie: zamiast formularza płatności klient widzi kod QR, skanuje go telefonem i kończy płatność na nim. Przydaje się przy BLIK-u i portfelach dostępnych wyłącznie na telefonie. Krok jest opcjonalny - pominięcie pola albo false oznacza, że checkout od razu pokazuje formularz płatności.

Kod QR pojawia się wyłącznie na desktopie. Na telefonie oraz przy ustawionym details.triggerPayment checkout pomija ten krok niezależnie od wartości pola.

3. Przekierowanie klienta

window.location.href = data.redirectUrl;

Po zakończonej płatności checkout pokazuje ekran potwierdzenia z przyciskiem „Wróć do sklepu”. Dopiero kliknięcie tego przycisku przenosi klienta pod adres podany w details.returnUrl - do URL-a nie są doklejane żadne parametry.

Powrót na returnUrl nie jest potwierdzeniem płatności - i wcale nie musi nastąpić. Klient, który zamknie kartę po zapłaceniu, nigdy nie trafi na Twój adres, a sam returnUrl to zwykły publiczny URL, który można otworzyć bez płacenia. Zamówienie realizuj wyłącznie po otrzymaniu i zweryfikowaniu webhooka.

4. Powtórne użycie `externalId`

externalId jest kluczem płatności po stronie Paymove. Ponowne wysłanie żądania z tym samym externalId nie tworzy nowej płatności ani nie zwraca błędu - API odpowiada 200 i zwraca redirectUrl płatności utworzonej wcześniej.

Przy powtórzeniu nowa wartość price i pozostałe pola są po cichu odrzucane. Jeśli ponowisz żądanie ze skorygowaną kwotą, obowiązywać będzie kwota pierwotna, a odpowiedź niczym tego nie zasygnalizuje. Dla każdego zamówienia używaj nowego, unikalnego externalId.

Aby zmienić kwotę istniejącej płatności, użyj osobnego wywołania:

curl --request PATCH \
  --url https://gateway-api.sandbox.paymove.io/api/pay/product/891412c8-8717-4449-9543-e34112bec470/subproduct/order-123 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{ "price": 1500 }'

Wywołanie aktualizuje wyłącznie price - pozostałe pola są pomijane.

5. Co dalej

Weryfikacja podpisu webhooka

Obowiązkowy krok przed realizacją zamówienia.

Statusy płatności

Statusy, payload webhooka i sprawdzanie stanu płatności.

Kody błędów

Pełna lista błędów API i sposoby ich obsługi.

SDK JavaScript

Gotowy klient dla Node.js.

Wprowadzenie

Integracje

Tutoriale

Pomoc

1. Endpoint

Nagłówki

2. Przykładowe wywołanie

Parametry body

Odpowiedź

Błędy

Wskazanie metody płatności

Krok z kodem QR

3. Przekierowanie klienta

4. Powtórne użycie `externalId`

5. Co dalej

Weryfikacja podpisu webhooka

Statusy płatności

Kody błędów

SDK JavaScript

​1. Endpoint

​Nagłówki

​2. Przykładowe wywołanie

​Parametry body

​Odpowiedź

​Błędy

​Wskazanie metody płatności

​Krok z kodem QR

​3. Przekierowanie klienta

​4. Powtórne użycie externalId

​5. Co dalej

Weryfikacja podpisu webhooka

Statusy płatności

Kody błędów

SDK JavaScript

1. Endpoint

Nagłówki

2. Przykładowe wywołanie

Parametry body

Odpowiedź

Błędy

Wskazanie metody płatności

Krok z kodem QR

3. Przekierowanie klienta

4. Powtórne użycie `externalId`

5. Co dalej