Zwroty

Zwrot płatności zlecisz samodzielnie, jednym wywołaniem HTTP. Pod tym samym adresem GET zwraca listę zwrotów danej płatności, więc po zleceniu zwrotu sprawdzasz jego stan tam, gdzie go zleciłeś.

Zwroty przez API nie są dostępne dla każdego partnera. To funkcja włączana indywidualnie, po uprzednim zgłoszeniu do Paymove - nie zakładaj, że Twoje konto ją ma, dopóki tego nie potwierdzisz. Napisz na integration@paymove.io, żeby ją włączyć; dopóki nie jest aktywna, każde wywołanie kończy się kodem 403.

Wywołuj API wyłącznie po stronie serwera. Zwrot przenosi pieniądze - klucz API nigdy nie może trafić do kodu frontendowego.

1. Endpointy

POST https://gateway-api.sandbox.paymove.io/api/pay/payment/{orderId}/refund
GET  https://gateway-api.sandbox.paymove.io/api/pay/payment/{orderId}/refund

Jedna ścieżka, dwie metody: POST tworzy zwrot, GET zwraca listę zwrotów tej płatności.

Ś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

POST wymaga klucza z uprawnieniem do zapisu, GET - do odczytu. Klucz bez wymaganego uprawnienia kończy się kodem 401; właściwy wygenerujesz w Panelu.

Segment pay w ścieżce wskazuje bramkę płatniczą. Pozostałe produkty paymove mają własne segmenty (go, parking, multi) - zwrot wykonuj pod segmentem produktu, w ramach którego powstała płatność.

Skąd wziąć `orderId`

{orderId} to wewnętrzny identyfikator zamówienia nadany przez Paymove, na przykład PAY1784798914400. Masz go w dwóch miejscach:

w polu orderId payloadu webhooka,
w odpowiedzi zapytania o status płatności.

orderId to nie jest Twój externalId ani 10-znakowy skrót płatności z redirectUrl. Ani jednego, ani drugiego nie da się użyć w tej ścieżce. Zapisz orderId u siebie przy obsłudze webhooka - inaczej przed każdym zwrotem będziesz musiał odpytać o status płatności.

2. Wykonanie zwrotu

curl --request POST \
  --url https://gateway-api.sandbox.paymove.io/api/pay/payment/PAY1784798914400/refund \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data '{
    "amountMinor": 15000,
    "email": "klient@example.com",
    "reason": "Klient zrezygnował z zamówienia"
  }'

To samo w Node.js:

const url = `https://gateway-api.sandbox.paymove.io/api/pay/payment/${orderId}/refund`;

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.PAYMOVE_API_KEY,
  },
  body: JSON.stringify({
    amountMinor: Math.round(150.0 * 100), // zawsze liczba całkowita w groszach
    email: "klient@example.com",
    reason: "Klient zrezygnował z zamówienia",
  }),
});

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

const refund = await response.json();
console.log(refund.id, refund.status); // np. "9f2c1b44-…" "PENDING"

Najkrótsze poprawne żądanie to puste body {} - zwraca całą kwotę płatności.

Parametry body

Pole	Typ	Wymagane	Opis
`amountMinor`	`integer`	Nie	Kwota zwrotu w groszach. Jeśli ją podasz, musi być równa pełnej kwocie płatności - zwroty częściowe nie są obsługiwane. Pominięcie pola zwraca całą kwotę
`email`	`string`	Nie	Adres e-mail płatnika. Używany przy autoryzacji poprzedzającej zwrot; bez niego wstawiana jest wartość zastępcza. Płatności przyjęte bez adresu e-mail (np. z terminala QR) zwracają się poprawnie i bez tego pola
`reason`	`string`	Nie	Dowolny tekst, zapisywany przy zwrocie i zwracany w polu `comment`

Żądanie nie zawiera productId. Produkt - a wraz z nim dane rozliczeniowe - Paymove odczytuje z samej płatności. Jeśli wyślesz productId, zostanie po cichu zignorowany, jak każde nieznane pole.

Zwróć uwagę na nazwę pola: tutaj kwota to amountMinor, podczas gdy przy tworzeniu płatności jest to price. Jednostka jest w obu miejscach ta sama - grosze jako liczba całkowita.

Odpowiedź

POST zwraca jeden zwrot, GET tablicę obiektów dokładnie tego samego typu - jeden parser obsłuży oba wywołania.

{
  "id": "9f2c1b44-6d2f-4f0e-9a71-2b8c5d3e1a90",
  "type": "REFUND",
  "orderId": "PAY1784798914400-r1",
  "parentOrderId": "PAY1784798914400",
  "amountMinor": 15000,
  "status": "PENDING",
  "paymentMethod": "BLIK",
  "partnerId": "3a7d1f52-8b64-4c19-9e03-7d2a5f8c1b44",
  "productId": "891412c8-8717-4449-9543-e34112bec470",
  "locale": "pl",
  "comment": "Klient zrezygnował z zamówienia",
  "createdAt": "2026-10-06T11:42:03Z",
  "updatedAt": "2026-10-06T11:42:04Z"
}

Pole	Opis
`id`	Identyfikator zwrotu w Paymove
`type`	Zawsze `REFUND`
`orderId`	Identyfikator samego zwrotu, w postaci `{orderId płatności}-rN`
`parentOrderId`	`orderId` zwracanej płatności - ten, który podałeś w ścieżce
`amountMinor`	Zwrócona kwota w groszach
`status`	Status zwrotu
`paymentMethod`	Metoda płatności, którą zapłacono zwracaną płatność
`partnerId`	Twój identyfikator partnera
`productId`	UUID produktu, w ramach którego powstała płatność
`locale`	Locale płatności
`comment`	Tekst przekazany w `reason`
`createdAt`, `updatedAt`	Znaczniki czasu w formacie ISO 8601 (UTC)

orderId w odpowiedzi to identyfikator zwrotu, nie płatności. Identyfikator płatności znajdziesz w parentOrderId. Zapisanie orderId zwrotu jako identyfikatora płatności to najłatwiejsza do popełnienia pomyłka na tej stronie.

3. Statusy zwrotu

Pole status przyjmuje te same wartości co status płatności:

Status	Znaczenie	Końcowy
`INITIALIZED`	Zwrot zapisany, jeszcze nie skierowany do rozliczenia	Nie
`PENDING`	Zwrot w toku	Nie
`WAITING_FOR_EXTERNAL_ACTION`	Stan przejściowy wewnątrz Paymove	Nie
`COMPLETED`	Zwrot rozliczony - jedyny status oznaczający sukces	Tak
`CANCELED`	Zwrot anulowany	Tak
`ERROR`	Zwrot nie powiódł się	Tak

Kod 200 nie znaczy, że pieniądze wróciły do klienta. Oznacza, że Paymove przyjął zwrot do realizacji - typową odpowiedzią jest status: "PENDING". Stan końcowy sprawdzaj przez GET …/refund; zwroty rozliczają się zwykle w ciągu kilkudziesięciu sekund.

Udany zwrot ustawia status całej płatności na REFUNDED.

4. Lista zwrotów płatności

curl --request GET \
  --url https://gateway-api.sandbox.paymove.io/api/pay/payment/PAY1784798914400/refund \
  --header 'X-API-KEY: sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

[
  {
    "id": "9f2c1b44-6d2f-4f0e-9a71-2b8c5d3e1a90",
    "type": "REFUND",
    "orderId": "PAY1784798914400-r1",
    "parentOrderId": "PAY1784798914400",
    "amountMinor": 15000,
    "status": "COMPLETED",
    "paymentMethod": "BLIK",
    "comment": "Klient zrezygnował z zamówienia",
    "createdAt": "2026-10-06T11:42:03Z",
    "updatedAt": "2026-10-06T11:42:31Z"
  }
]

Płatność bez zwrotów zwraca pustą tablicę []. To właściwy endpoint do odpytywania o stan zwrotu - polling po kilku sekundach, aż status będzie końcowy.

Lista zawiera także nieudane próby. Każdy zwrot zapisujemy przed skierowaniem go do rozliczenia, więc próba odrzucona od razu nie przepada - POST odpowiada wtedy 400, a na liście widać ją ze statusem ERROR.

5. Czego nie da się zwrócić

Każdy z tych przypadków kończy się kodem 400:

Płatność nieukończona. Zwrócić można wyłącznie płatność ze statusem COMPLETED. Płatności INITIALIZED, PENDING, CANCELED i ERROR nie ma po co zwracać.
Płatność, która ma już zwrot. Istniejący zwrot w stanie PENDING lub COMPLETED blokuje kolejne próby - jeden zwrot na płatność.
Kwota inna niż pełna. amountMinor różne od kwoty płatności jest odrzucane; zwroty częściowe nie są obsługiwane.
Części płatności nie da się zwrócić przez API w ogóle - zależy to od sposobu, w jaki zostały rozliczone. Jeśli dostajesz 400 przy ukończonej płatności i pełnej kwocie, napisz na integration@paymove.io - zwrot wykonamy za Ciebie.

Zwroty płatności PayPo są obsługiwane, ale potwierdzenie przychodzi asynchronicznie - odpowiedź POST ma zawsze status: "PENDING", nigdy od razu COMPLETED.

6. Ograniczenia

Brak zwrotów częściowych i jeden zwrot na płatność. amountMinor musi być równe pełnej kwocie płatności, a druga próba zwrotu tej samej płatności jest odrzucana. Oba ograniczenia wynikają z tego, że zwrot rozlicza się pod referencją samej płatności - drugi byłby nie do odróżnienia od pierwszego.

Nie ma klucza idempotencji. Dwa identyczne żądania to dwa zwroty - dziś drugi z nich zatrzyma kontrola „jeden zwrot na płatność”, ale nie buduj na tym logiki ponawiania. Zanim ponowisz POST, sprawdź GET …/refund.

7. Kody statusów

Status	Kiedy
`200`	Zwrot przyjęty do realizacji albo lista zwrotów zwrócona poprawnie. Nie oznacza, że pieniądze już wróciły
`400`	Płatność nieukończona; `amountMinor` różne od pełnej kwoty; płatność ma już zwrot; płatność bez przypisanego produktu, więc nie da się ustalić danych rozliczeniowych; płatności nie da się zwrócić przez API; zwrot odrzucony
`401`	Brak nagłówka `X-API-KEY`, klucz nierozpoznany albo klucz bez uprawnienia do zapisu (`POST`) lub odczytu (`GET`)
`403`	Zwroty przez API nie są włączone dla Twojego konta, płatność należy do innego partnera albo płatność nie istnieje
`404`	Niespójność danych po stronie Paymove - płatność istnieje, ale brakuje jej rekordu źródłowego. Zgłoś to na integration@paymove.io; to nie jest błąd po Twojej stronie

Płatność, która nie istnieje, i płatność należąca do innego partnera zwracają ten sam kod 403. Jest to zamierzone - 404 potwierdzałoby, które identyfikatory zamówień istnieją w Paymove. Nie wnioskuj z 403 o tym, czy płatność istnieje.

Własność płatności jest częścią wyszukiwania, a nie kontrolą po nim: płatność szukamy po orderId i po partnerze, do którego należy Twój klucz. Nie da się więc zwrócić płatności innego partnera ani skierować zwrotu na jego dane rozliczeniowe.

8. Zalecany przepływ

Przy obsłudze webhooka zapisz u siebie orderId płatności obok swojego externalId.
Przed zwrotem upewnij się, że płatność ma status COMPLETED i że nie zwróciłeś jej już wcześniej - GET …/refund.
Wyślij POST …/refund. Zapisz id i orderId zwrotu z odpowiedzi.
Odpytuj GET …/refund, aż status zwrotu będzie końcowy. COMPLETED oznacza zwrot rozliczony; ERROR - odrzucony.
Dopiero po COMPLETED oznacz zwrot jako zrealizowany u siebie.

Co dalej

Statusy płatności

Skąd wziąć orderId i jak sprawdzić status płatności.

Kody błędów

Format błędów i mechanizmy, których API nie posiada.

REST API

Tworzenie płatności, którą potem zwracasz.

Wsparcie

Kontakt, gdy zwrotu nie da się wykonać przez API.

Wprowadzenie

Integracje

Tutoriale

Pomoc

1. Endpointy

Nagłówki

Skąd wziąć `orderId`

2. Wykonanie zwrotu

Parametry body

Odpowiedź

3. Statusy zwrotu

4. Lista zwrotów płatności

5. Czego nie da się zwrócić

6. Ograniczenia

7. Kody statusów

8. Zalecany przepływ

Co dalej

Statusy płatności

Kody błędów

REST API

Wsparcie

​1. Endpointy

​Nagłówki

​Skąd wziąć orderId

​2. Wykonanie zwrotu

​Parametry body

​Odpowiedź

​3. Statusy zwrotu

​4. Lista zwrotów płatności

​5. Czego nie da się zwrócić

​6. Ograniczenia

​7. Kody statusów

​8. Zalecany przepływ

​Co dalej

Statusy płatności

Kody błędów

REST API

Wsparcie

1. Endpointy

Nagłówki

Skąd wziąć `orderId`

2. Wykonanie zwrotu

Parametry body

Odpowiedź

3. Statusy zwrotu

4. Lista zwrotów płatności

5. Czego nie da się zwrócić

6. Ograniczenia

7. Kody statusów

8. Zalecany przepływ

Co dalej