Bramka płatnicza: podstawowa integracja

Podstawowy scenariusz integracji z bramką płatniczą Paymove składa się z trzech kroków: jednorazowo tworzysz produkt (reprezentujący Twój sklep) i konfigurujesz webhook, a następnie dla każdego zamówienia tworzysz płatność i przekierowujesz klienta na otrzymany redirectUrl. Wszystkie żądania autoryzujesz kluczem API przekazywanym w nagłówku X-API-KEY.

Przykłady używają środowiska sandbox: https://gateway-api.sandbox.paymove.io. Klucz API i partnerId otrzymasz od Paymove.

Krok 1: Utworzenie produktu (sklepu)

Produkt reprezentuje Twój sklep w systemie Paymove - wszystkie płatności tworzysz w jego ramach. 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": "Sklep Testowy",
    "shortName": "SHOP1",
    "location": "Warszawa",
    "timezone": "Europe/Warsaw",
    "productMetadata": { "locale": "pl-PL" }
  }'

Odpowiedź (200):

{
  "id": "891412c8-8717-4449-9543-e34112bec470",
  "name": "Sklep Testowy",
  "location": "Warszawa",
  "partner": {
    "id": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "name": "Nazwa Partnera Sp. z o.o.",
    "productTypes": ["PAY"]
  },
  "timezone": "Europe/Warsaw",
  "shortName": "SHOP1",
  "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": 1783246791.745352526,
  "updatedAt": 1783246791.745352526
}

Pole id z odpowiedzi to productId - identyfikator Twojego sklepu używany w kolejnych krokach.

Krok 2: Konfiguracja webhooka

Webhook powiadamia Twój system o zakończonej płatności. Najpierw go rejestrujesz, potem przypisujesz do produktu. W requestTemplate możesz użyć zmiennych {{externalId}} (Twój orderId) i {{price}} (kwota) - Paymove podstawi je przy wysyłce.

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "name": "OrderPaymentHook",
    "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": "78562c79-2f5c-4415-8af4-c871eea92ef2",
    "type": "PAYMENT",
    "headers": { "Content-Type": ["application/json"] }
  }'

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

{
  "id": "6b23ecd9-14c8-47fc-add0-b71ec50e9d66",
  "name": "OrderPaymentHook",
  "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,
  "type": "PAYMENT",
  "headers": { "Content-Type": ["application/json"] },
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

signingSecret służy do weryfikacji podpisu żądań przychodzących od Paymove. Zapisz go bezpiecznie po stronie swojego systemu.

Następnie przypisz webhook do produktu (podmień webhookId i productId):

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/plugin/webhook/6b23ecd9-14c8-47fc-add0-b71ec50e9d66/products/891412c8-8717-4449-9543-e34112bec470 \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Odpowiedź (200): obiekt webhooka potwierdzający powiązanie.

Krok 3: Utworzenie płatności

Dla każdego zamówienia tworzysz płatność w ramach produktu. W URL podmień productId z kroku 1.

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",
      "customerId": "user-567",
      "email": "klient@example.com",
      "locale": "pl-PL",
      "triggerPayment": "BLIK"
    }
  }'

Pole	Wymagane	Opis
`price`	Tak	Kwota w groszach jako liczba całkowita (np. `1000` = 10,00 PLN). Waluta to zawsze PLN.
`externalId`	Tak	Unikalny identyfikator zamówienia w Twoim systemie.
`details.returnUrl`	Tak	URL powrotu klienta po płatności.
`details.productName`	Nie	Nazwa produktu widoczna na checkoucie.
`details.customerId`	Nie	Dowolna wartość przekazywana na wylot - checkout jej nie wyświetla.
`details.email`	Nie	Adres e-mail klienta, uzupełniany na checkoucie.
`details.locale`	Nie	Nadpisuje locale z głównego produktu (np. `pl-PL`).
`details.triggerPayment`	Nie	Metoda wybrana z góry w checkoucie - `BLIK`, `GPAY`, `APAY`, `TRANSFER`, `PAY_BY_LINK` lub `PAYPO`. Automatycznie startują wyłącznie `GPAY` i `APAY` (i tylko z `details.email`); pozostałe są jedynie zaznaczone. Szczegóły: REST API.
`details.qrStepEnabled`	Nie	`true` sprawia, że na desktopie checkout zaczyna od kodu QR, a klient kończy płatność na telefonie. Szczegóły: REST API.
`details.autoclose`	Nie	Po ilu ms od udanej płatności checkout sam wraca na `returnUrl`, z odliczaniem w przycisku „Wróć do sklepu”. Szczegóły: REST API.

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

Odpowiedź (200):

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

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

Krok 4: Przekierowanie klienta

Przekieruj klienta na otrzymany redirectUrl:

window.location.href = data.redirectUrl;

Klient zobaczy stronę checkoutu Paymove z kwotą, nazwą Twojego sklepu i produktu oraz metodami płatności (BLIK, Google Pay, Apple Pay, przelew). Po zakończonej płatności:

Paymove wyśle webhook na Twój endpoint - domyślnie tylko dla statusu COMPLETED.
Twój system weryfikuje nagłówek X-Paymove-Signature (jak to zrobić), odpowiada 200 i { "status": "ok" }, po czym realizuje zamówienie.
Klient widzi ekran potwierdzenia i może wrócić do sklepu pod adres returnUrl.

Nie realizuj zamówienia w obsłudze returnUrl. Przekierowanie jest sterowane przez przeglądarkę klienta i można je wywołać bez opłacenia płatności. Jedynym wiarygodnym potwierdzeniem jest zweryfikowany webhook.

Wprowadzenie

Integracje

Tutoriale

Pomoc

Bramka płatnicza: podstawowa integracja

Krok 1: Utworzenie produktu (sklepu)

Krok 2: Konfiguracja webhooka

Krok 3: Utworzenie płatności

Krok 4: Przekierowanie klienta

Co dalej?

Bramka płatnicza: webhooki

SDK JavaScript

​Krok 1: Utworzenie produktu (sklepu)

​Krok 2: Konfiguracja webhooka

​Krok 3: Utworzenie płatności

​Krok 4: Przekierowanie klienta

​Co dalej?

Bramka płatnicza: webhooki

SDK JavaScript

Krok 1: Utworzenie produktu (sklepu)

Krok 2: Konfiguracja webhooka

Krok 3: Utworzenie płatności

Krok 4: Przekierowanie klienta

Co dalej?