To jest API V1, które nie jest już utrzymywane

Aby zapoznać się z aktualną dokumentacją, zobacz najnowszą wersję.

Zwroty

Płatność może zostać zwrócona wielokrotnie na łączną kwotę nieprzekraczającą kwoty płatności i jest to dozwolone tylko w przypadku płatności w statusie CONFIRMED. Paynow akceptuje zwroty z minimalną kwotą 1 PLN dla płatności kartą a dla innych metod 0,01 PLN.

Uwaga

Aby móc dokonać zwrotu za pomocą API, Twój sklep musi mieć włączoną opcję „dziennie” w Harmonogramie wypłat dla danego sklepu. Środki potrzebne do dokonania zwrotu zostaną pobrane z Twojego salda.

Zwroty oczekujące - opcjonalne

Zwrot oczekujący to specjalny rodzaj zwrotu, który można zainicjować nawet jeśli kwota zwrotu przekracza saldo. Po zainicjowaniu taki zwrot będzie miał status NEW. Po zgromadzeniu wystarczającej ilości środków na saldzie zwroty zostaną przetworzone przy użyciu algorytmu FIFO (co oznacza, że zwroty są przetwarzane w kolejności, w jakiej zostały zainicjowane).

Jeśli nie zgromadzisz wymaganych środków na zwrot na saldzie przez 120 godzin (5 dni, wartość domyślna), status zwrotu zmieni się na CANCELLED.

Możesz zmienić czas, po którym zwroty oczekujące zostaną anulowane - jednostką tego parametru jest godzina.

Aby włączyć tę funkcję w swoim sklepie i/lub zmienić domyślny czas anulowania zwrotu oczekującego (opcjonalnie), przejdź do zakładki Ustawienia > Zwroty oczekujące w Panelu Merchanta.

Diagram procesu zwrotu

Poniższy diagram sekwencji przedstawia proces zwrotu zakończony sukcesem:

Mapa statusów zwrotu

Na poniższym obrazku przedstawiono wszystkie statusy, jakie może przyjąć zwrot, oraz możliwe przejścia między nimi:

Wyjaśnienie:

Code	Description
NEW	Zwrot został zaakceptowany.
PENDING	Paynow rozpoczyna przetwarzanie żądania zwrotu.
SUCCESSFUL	Zwrot został pomyślnie przetworzony przez Paynow, a pieniądze zostały przelane na konto kupującego.
FAILED	Wystąpił problem podczas przetwarzania zwrotu. Pieniądze nie zostały przelane na rzecz kupującego.
CANCELLED	Zwrot został anulowany. Pieniądze nie zostały przelane na rzecz kupującego. Anulować można tylko zwroty o statusie NEW.

Utwórz zwrot

Na potrzeby tego przewodnika przyjmiemy założenie, że dane autoryzacyjne to:

• Api-Key = 97a55694-5478-43b5-b406-fb49ebfdd2b5
• Signature-Key = b305b996-bca5-4404-a0b7-2ccea3d2b64b

Załóżmy również, że paymentId to NOR3-FUN-D4U-LOL

Krok 1: Przygotuj wiadomość z żądaniem zwrotu. W tym przykładzie użyjemy prostej wiadomości zawierającej tylko wymagane pola, które wyglądają następująco:

{
  "amount": 997,
  "reason": "RMA"
}

Podana kwota powinna być podana w najmniejszej jednostce waluty zwrotu (grosz w przypadku PLN). Oznacza to, że powyższe żądanie definiuje zwrot w wysokości 9,97 PLN. Pole opisu powinno zawierać powód zwrotu. Pełną specyfikację wiadomości żądania zwrotu można znaleźć poniżej.

Krok 2: Dołącz nagłówek Api-Key z wartością Api-Key, którą znajdziesz w Panelu Merchanta.

Krok 3: Oblicz podpis i dołącz go jako nagłówek Signature. Dla podanego przykładu prawidłowy podpis to IExnDYF3U/A6y0UKm6VnuOMz0+uXsxMcZRg8h4QgZAE=

Ważne

Jeśli próbujesz obliczyć podpis z przykładu w swoim kodzie i otrzymujesz inny wynik, upewnij się, że Twoja wiadomość JSON jest sformatowana w ten sam sposób, co wiadomość w przykładzie, tj. z wcięciem czterech spacji i bez znaku nowej linii na końcu.

Krok 4: Wygeneruj losowy ciąg o maksymalnej długości 45 znaków dla nagłówka Idempotency-Key.

Krok 5: Wykonaj żądanie POST z przygotowaną wiadomością na endpoint żądania zwrotu

  curl --request POST 'https://api.sandbox.paynow.pl/v1/payments/NOR3-FUN-D4U-LOL/refunds' \
  -H 'Content-Type: application/json' \
  -H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
  -H 'Signature: IExnDYF3U/A6y0UKm6VnuOMz0+uXsxMcZRg8h4QgZAE=' \
  -H 'Idempotency-Key: 59c6dd26-f905-487b-96c9-fd1d2bd76885' \
  --data-raw '{
  "amount": 997,
  "reason": "RMA"
}'

Uwaga

Pamiętaj, że żądanie musi zawierać nagłówki Host i Accept jak opisano tutaj. Nie są one wymienione powyżej, ponieważ polecenie curl domyślnie je zawiera.

Krok 6: Obsłuż zwróconą odpowiedź:

{
  "refundId": "R3FU-UND-D8K-WZD",
  "status": "PENDING"
}

Odpowiedź zawiera ID zwrotu wygenerowanego przez Paynow i aktualny status zwrotu. Zwrócony refundId powinien zostać zapisany przez Merchanta w celu późniejszego wykorzystania.

Krok 7: Zapytaj o status zwrotu. Sprawdź opis endpointu żądania statusu.

  curl --location --request GET 'https://api.sandbox.paynow.pl/v1/refunds/R3FU-UND-D8K-WZD/status' \
  --header 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5'

Aby zobaczyć więcej szczegółów na temat statusów, zapoznaj się z Mapą statusów zwrotu

Anulowanie zwrotu oczekującego

Jeśli włączyłeś mechanizm Zwrotów oczekujących każdy nowy zwrot salda zostanie wykonany z pewnym opóźnieniem. Kiedy zwrot ma status NEW (oczekiwanie), możesz go anulować za pomocą żądania API. Poniżej możesz zobaczyć, jak to zrobić.

Na potrzeby tego przewodnika przyjmiemy założenie, że dane autoryzacyjne to:

• Api-Key = 97a55694-5478-43b5-b406-fb49ebfdd2b5
• Refund Id = RE1-K7E-206-31J

Krok 1: Wygeneruj losowy ciąg o maksymalnej długości 45 znaków dla nagłówka Idempotency-Key.

Krok 2: Wykonaj poniższe żądanie do naszego API:

curl --location --request POST 'https://api.sandbox.paynow.pl/v1/refunds/RE1-K7E-206-31J/cancel' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Idempotency-Key: a796913a-4a56-4be3-8145-abb1c9da377d' \

Należy pamiętać, że za pomocą tego żądania można anulować zwroty z salda, tylko dla statusu NEW.