Statusy płatności

Statusy

Status	Znaczenie	Końcowy
`INITIALIZED`	Płatność utworzona, klient jeszcze nie zapłacił	Nie
`PENDING`	Płatność w toku po stronie operatora	Nie
`COMPLETED`	Płatność zakończona sukcesem - realizuj zamówienie	Tak
`CANCELED`	Klient anulował płatność	Tak
`ERROR`	Płatność nie powiodła się	Tak
`REFUNDED`	Płatność zwrócona	Tak
`WAITING_FOR_EXTERNAL_ACTION`	Stan przejściowy wewnątrz Paymove	Nie

WAITING_FOR_EXTERNAL_ACTION to stan przejściowy, ustawiany na chwilę w trakcie przetwarzania po stronie Paymove. Nie jest stanem końcowym i nie oznacza, że płatność wymaga działania klienta. Możesz go zobaczyć, odpytując API w niefortunnym momencie - potraktuj go jak PENDING.

Zwróć uwagę na pisownię CANCELED - przez jedno „l”.

Payload webhooka

Kształt zależy od tego, czy przy rejestracji webhooka ustawiłeś requestTemplate.

Bez `requestTemplate`

Paymove wysyła pełny obiekt płatności. Pola bez wartości są pomijane, więc konkretne powiadomienie może zawierać ich mniej:

{
  "id": "891412c8-8717-4449-9543-e34112bec470",
  "name": "MerchantShop",
  "fullName": "Merchant Shop Sp. z o.o.",
  "shortName": "MShop",
  "location": "PL",
  "externalId": "order-123",
  "orderId": "PAY1784798914400",
  "price": 1000,
  "status": "COMPLETED",
  "paymentMethod": "BLIK",
  "email": "klient@example.com",
  "date": 1783246791.745352526,
  "activeFrom": 1783246791.740112000,
  "requestId": "8f2b1c44-0d7e-4a91-b2c3-5e7f9a1d3c60"
}

Pole	Opis
`id`	UUID Twojego produktu (sklepu), nie płatności
`name`, `fullName`, `shortName`, `location`	Dane produktu z konfiguracji
`externalId`	Twój identyfikator zamówienia - po nim dopasujesz płatność
`orderId`	Wewnętrzny identyfikator zamówienia w Paymove
`price`	Kwota w groszach - ta sama, którą podałeś przy tworzeniu płatności
`status`	Status płatności
`paymentMethod`	Użyta metoda płatności
`email`	Adres e-mail klienta, jeśli był znany
`date`	Czas utworzenia płatności (epoka uniksowa)
`activeFrom`	Czas utworzenia zamówienia (epoka uniksowa)
`requestId`	Identyfikator żądania, przydatny przy zgłoszeniach do wsparcia

price odpowiada kwocie, którą podałeś przy tworzeniu płatności, więc możesz porównać ją z wartością zapisaną u siebie. Klient widzi na checkoucie tę kwotę powiększoną o prowizję, jeśli Twój produkt ją nalicza.

Payload nie zawiera pola event ani type i nie jest opakowany w kopertę. To płaski obiekt, a rodzaj zdarzenia rozpoznajesz po polu status.

Z `requestTemplate`

Payload to dokładnie to, co wyrenderuje Twój szablon. Dla szablonu {"orderId": "{{externalId}}", "price": "{{price}}"} otrzymasz:

{
  "orderId": "order-123",
  "price": "1000"
}

W szablonie możesz użyć każdego pola domyślnego payloadu - w tym {{status}}, {{paymentMethod}}, {{email}}, {{date}} czy {{orderId}}, nie tylko {{externalId}} i {{price}}. Zwróć uwagę, że wartości wstawiane do szablonu tekstowego trafiają do payloadu jako łańcuchy znaków.

Szablon wymusza własny kształt payloadu i zawiera wyłącznie to, co w nim wypiszesz. Jeśli chcesz rozróżniać statusy, dodaj {{status}} do szablonu albo w ogóle nie ustawiaj requestTemplate.

Sprawdzenie statusu zapytaniem

Przydatne jako uzupełnienie webhooka - na przykład gdy klient wrócił na returnUrl, a powiadomienie jeszcze nie dotarło.

Ten endpoint działa pod innym adresem bazowym niż reszta API. Nie jest routowany przez gateway-api.sandbox.paymove.io ani api.paymove.io - wywołanie tam zwróci 404 z odpowiedzią text/plain o treści No route found for: GET …, czyli nawet nie w standardowym formacie {status, message}.

Środowisko	Adres bazowy dla zapytania o status
Sandbox	`https://pay-api.sandbox.paymove.io`
Produkcja	`https://pay-api.paymove.io`

curl "https://pay-api.sandbox.paymove.io/api/payment/product/{productId}/subproduct/{paymentHash}/status"

{
  "status": "COMPLETED",
  "orderId": "PAY1784798914400"
}

Parametr	Opis
`productId`	UUID Twojego produktu lub jego `shortName`
`paymentHash`	10-znakowy skrót płatności z parametru `externalId` w `redirectUrl`

Gdy płatność o podanym skrócie nie istnieje, otrzymasz:

{
  "status": 404,
  "message": "Payments for externalId ec6RtwTZKb not found"
}

paymentHash to nie jest externalId przekazany przy tworzeniu płatności. To wartość wygenerowana przez Paymove, którą otrzymujesz w redirectUrl - na przykład ec6RtwTZKb w adresie https://checkout.sandbox.paymove.io/{productId}?externalId=ec6RtwTZKb. Zapisz ją przy tworzeniu płatności.

Endpoint nie wymaga klucza API. Nie przekazuj do niego danych wrażliwych i nie traktuj samej odpowiedzi jako jedynego dowodu płatności w krytycznych przepływach - wiarygodnym potwierdzeniem jest zweryfikowany webhook.

Zalecany przepływ

Utwórz płatność i zapisz u siebie externalId oraz skrót płatności z redirectUrl.
Przekieruj klienta na checkout.
Na stronie returnUrl pokaż komunikat „przetwarzamy płatność” - bez realizacji zamówienia.
Poczekaj na webhook, zweryfikuj jego podpis i zrealizuj zamówienie idempotentnie.
Jeśli po powrocie klienta webhook jeszcze nie dotarł, możesz odpytać o status, żeby od razu pokazać właściwy komunikat.

Zwroty

Zwroty realizuje Paymove - nie ma publicznego endpointu API do ich wykonywania. Jeśli potrzebujesz zwrócić płatność, skontaktuj się z integration@paymove.io. Po wykonaniu zwrotu płatność przyjmuje status REFUNDED.

Wprowadzenie

Integracje

Tutoriale

Pomoc

Statusy

Payload webhooka

Bez `requestTemplate`

Z `requestTemplate`

Sprawdzenie statusu zapytaniem

Zalecany przepływ

Zwroty

Co dalej

Weryfikacja podpisu

Konfiguracja webhooka

​Statusy

​Payload webhooka

​Bez requestTemplate

​Z requestTemplate

​Sprawdzenie statusu zapytaniem

​Zalecany przepływ

​Zwroty

​Co dalej

Weryfikacja podpisu

Konfiguracja webhooka

Statusy

Payload webhooka

Bez `requestTemplate`

Z `requestTemplate`

Sprawdzenie statusu zapytaniem

Zalecany przepływ

Zwroty

Co dalej