Przejdź do głównej zawartości

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:

business flow image

Mapa statusów zwrotu​

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

business flow image

Wyjaśnienie:

CodeDescription
NEWZwrot został zaakceptowany.
PENDINGPaynow rozpoczyna przetwarzanie żądania zwrotu.
SUCCESSFULZwrot został pomyślnie przetworzony przez Paynow, a pieniądze zostały przelane na konto kupującego.
FAILEDWystąpił problem podczas przetwarzania zwrotu. Pieniądze nie zostały przelane na rzecz kupującego.
CANCELLEDZwrot 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 żądanien zwrotu. W tym przykładzie użyjemy prostej wiadomości zawierającej tylko wymagane pola, które wyglądają następująco:

{
  "amount": 100,
  "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 1,00 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 o5HQfxngBqr68sLOEtJu0fd1Cl/GzfehZEswk6KMb0w=

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 --location 'https://api.sandbox.paynow.pl/v3/payments/NOM3-VWX-YS7-J43/refunds' \
--header 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
--header 'Signature: o5HQfxngBqr68sLOEtJu0fd1Cl/GzfehZEswk6KMb0w=' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 100
}'
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": "RE6-9YD-ULU-MRL",
  "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 zapytania o status.

  curl --location --request GET 'https://api.sandbox.paynow.pl/v3/refunds/RE6-9YD-ULU-MRL/status' \
  --header 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
  --header 'Idempotency-Key: 6228e8f1-4fd9-40bc-9660-37b03c968590' \
  --header 'Signature: Aqy2xIQAZghJX4jdzeMZa7I/3WcI2saIAt0qzLoZiMU='

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]/docs/v3/refunds#awaiting-refunds-optional) 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łówkaIdempotency-Key.

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

curl --location --request POST 'https://api.sandbox.paynow.pl/v3/refunds/RE6-9YD-ULU-MRL/cancel' \
-H 'Api-Key: 97a55694-5478-43b5-b406-fb49ebfdd2b5' \
-H 'Signature: e3JjMoexXydWjfBX8ArbExJu8YhTycwKEk0uWc9rXuM='

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