Skip to main content

​
Statusy

Status jest zawsze przekazywany jako łańcuch znaków - "COMPLETED", nie liczba. Wartości liczbowe spotykane w starszych integracjach są wewnętrzną reprezentacją bazodanową i nie pojawiają się ani w API, ani w webhookach.
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”.

​
Kiedy przychodzi webhook

Domyślnie Paymove wysyła webhook wyłącznie dla statusu COMPLETED. Powiadomienia o CANCELED, ERROR czy REFUNDED wymagają włączenia po stronie Paymove dla konkretnego produktu. Jeśli ich potrzebujesz, napisz na integration@paymove.io.
Oznacza to, że w domyślnej konfiguracji brak webhooka nie odróżnia płatności nieudanej od płatności trwającej. Jeśli musisz rozpoznać nieudane płatności, użyj zapytania o status albo poproś o włączenie pełnych powiadomień.

​
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:
price w tym payloadzie to kwota po odjęciu prowizji, a nie kwota pobrana od klienta. Nie używaj go do weryfikacji, czy klient zapłacił właściwą sumę - porównuj z wartością zapisaną u siebie w momencie tworzenia płatności.
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:
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}.
Gdy płatność o podanym skrócie nie istnieje, otrzymasz:
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

  1. Utwórz płatność i zapisz u siebie externalId oraz skrót płatności z redirectUrl.
  2. Przekieruj klienta na checkout.
  3. Na stronie returnUrl pokaż komunikat „przetwarzamy płatność” - bez realizacji zamówienia.
  4. Poczekaj na webhook, zweryfikuj jego podpis i zrealizuj zamówienie idempotentnie.
  5. 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.

​
Co dalej

Weryfikacja podpisu

Obowiązkowy krok przed realizacją zamówienia.

Konfiguracja webhooka

Rejestracja webhooka i przypisanie go do produktu.