Przejdź do treści
/
Zwroty
Ostatnia aktualizacja

Zwroty

System SimPay pozwala na łatwe i zautomatyzowane zwracanie środków klientom (np. w przypadku odstąpienia od umowy, reklamacji czy anulowania zamówienia). Proces ten możesz zainicjować bezpośrednio z poziomu naszego API, bez konieczności ręcznego zlecania przelewów z poziomu Panelu Billingowego.

Wymogi formalne i techniczne

Zanim zlecisz zwrot, upewnij się, że dana transakcja spełnia wszystkie poniższe warunki. W przypadku niespełnienia któregokolwiek z nich, API zwróci błąd.

  • Status transakcji: Transakcja musi być w pełni opłacona (posiadać status transaction_paid).
  • Dostępne saldo: Na Twoim koncie (saldu w SimPay) musi znajdować się kwota wystarczająca na pokrycie zlecanego zwrotu.
  • Maksymalna kwota: Suma wszystkich dotychczasowych zwrotów dla danej transakcji nie może przekroczyć jej pierwotnej wartości.
  • Wiek transakcji: Zlecenie zwrotu jest możliwe tylko dla transakcji, które nie są starsze niż 30 dni.
  • Brak testów: Zwrotów można dokonywać wyłącznie dla rzeczywistych (produkcyjnych) transakcji. Nie można zlecić zwrotu dla transakcji testowej.
  • Brak duplikatów: W danym momencie do transakcji nie może być przypisane inne, oczekujące zlecenie zwrotu (status refund_new lub refund_pending). Musisz poczekać na zakończenie przetwarzania poprzedniego zlecenia.

Zwroty całkowite i częściowe

W zależności od potrzeb, SimPay umożliwia dwa rodzaje zwrotów:

  1. Zwrot częściowy – zwracasz klientowi tylko część kwoty (np. gdy odsyła tylko jeden z kilku zamówionych produktów). Aby go wykonać, przekaż w ciele zapytania (body) parametr amount z odpowiednią kwotą.
  2. Zwrot całkowity (100%) – zwracasz całą wpłaconą kwotę. Masz tutaj dwie możliwości: możesz pominąć parametr amount w żądaniu (wtedy system domyślnie zwróci całą wartość transakcji) lub jawnie podać pierwotną kwotę zamówienia.

Tworzenie zwrotu (Przykłady API)

Aby wygenerować zwrot, wyślij żądanie POST na endpoint: /payment/{serviceId}/transactions/{transactionId}/refunds

Przykład: Zwrot częściowy (np. na kwotę 25.50 PLN)

curl -X POST "https://api.simpay.pl/payment/{serviceId}/transactions/{transactionId}/refunds" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "amount": "25.50"
  }'

Przykład: Zwrot całkowity (pominięcie parametru amount)

curl -X POST "https://api.simpay.pl/payment/{serviceId}/transactions/{transactionId}/refunds" \
  -H "Authorization: Bearer TWÓJ_TOKEN_API" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{}'

Odpowiedź z API i identyfikator refundId

Po wysłaniu poprawnego żądania, operacja trafi do kolejki i otrzyma wstępny status refund_new. W odpowiedzi z naszego API otrzymasz obiekt zawierający unikalny identyfikator tego zlecenia – refundId.

Ważne: Pamiętaj, aby zapisać wartość refundId w swojej bazie danych obok identyfikatora transakcji! Będzie on niezbędny do poprawnego powiązania i obsłużenia przyszłych powiadomień IPN (webhooków) ze zmianami statusu dla tego konkretnego zwrotu.

Cykl życia zwrotu

Zlecenie zwrotu nie oznacza natychmiastowego pojawienia się pieniędzy na koncie klienta. Proces ten podlega określonym etapom i statusom systemowym.

👉 Przejdź do strony: Statusy zwrotów, aby sprawdzić pełny cykl życia, diagramy przejść oraz instrukcje, w jaki sposób powiadamiamy Twoją aplikację o udanym zakończeniu operacji zwrotu.

Poprzednia strona
Następna strona