# 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)


```bash
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)


```bash
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](/payment/statuses#statusGroup=Statusy+zwrot%C3%B3w)**, aby sprawdzić pełny cykl życia, diagramy przejść oraz instrukcje, w jaki sposób powiadamiamy Twoją aplikację o udanym zakończeniu operacji zwrotu.