# Statusy w SimPay

Wybierz interesujący Cię rodzaj statusów, aby dowiedzieć się więcej o ich znaczeniu i zastosowaniu w naszym systemie.

Statusy transakcji
Każda transakcja w systemie SimPay posiada swój cykl życia, który jest reprezentowany przez odpowiednie statusy. Zmiana
statusu informuje o aktualnym etapie procesowania płatności – od momentu jej zainicjowania, aż po udane zakończenie,
odrzucenie lub zwrot.

Poniższy diagram przedstawia możliwe ścieżki przejść pomiędzy poszczególnymi statusami transakcji w naszym API.

## Cykl życia transakcji

## Opis poszczególnych statusów

W odpowiedziach z naszego API status transakcji zwracany jest jako ciąg znaków (`string`). Poniższa tabela szczegółowo
wyjaśnia znaczenie każdego z nich:

| Status (`enum`) | Typ | Opis |
|  --- | --- | --- |
| `transaction_new` | **Procesowany** | Wstępny status po utworzeniu nowej transakcji w systemie. Płatność oczekuje na dalsze kroki. |
| `transaction_generated` | **Procesowany** | Klient wybrał interesującą go metodę płatności oraz przeszedł nią do zapłaty |
| `transaction_confirmed` | **Procesowany** | Metoda płatności poinformowała nas o rozpoczęciu inicjacji płatności. |
| `transaction_paid` | **Sukces** | Płatność została pomyślnie zrealizowana i środki zostały zabezpieczone. To główny status udanej transakcji. Można przystąpić do realizacji zamówienia |
| `transaction_failure` | **Błąd** | Płatność została odrzucona (np. brak środków na koncie, odmowa autoryzacji przez bank, błąd autoryzacji 3D Secure). |
| `transaction_expired` | **Błąd / Wygaśnięcie** | Upłynął czas przeznaczony na opłacenie transakcji. Ścieżka płatności zostaje bezpowrotnie zamknięta. |
| `transaction_refunded` | **Zwrot** | Dokonano pomyślnego i całkowitego zwrotu (100% kwoty) na konto płatnika. |
| `transaction_fraud_possibility` | **Weryfikacja** | System wykrył anomalię lub ryzyko. Transakcja wymaga dodatkowej weryfikacji przed ostatecznym zatwierdzeniem lub odrzuceniem. |
| `transaction_fraud` | **Błąd krytyczny** | Transakcja została oznaczona jako oszustwo (np. kradziona karta, chargeback). Środki nie zostaną przekazane. |


Wskazówka integracyjna
Status `transaction_paid` jest jedynym statusem oznaczającym poprawne i ostateczne opłacenie zamówienia przez klienta (
chyba, że później nastąpi zwrot).
Twoja aplikacja powinna realizować zamówienie (wydawać towar/usługę) dopiero po otrzymaniu webhooka z tym statusem.

## Jak zostajesz informowany o zmianach statusu?

Zmiany statusów transakcji oraz zwrotów zachodzą w naszym systemie asynchronicznie (np. po zatwierdzeniu płatności przez
bank). Aby Twoja aplikacja mogła natychmiast zareagować na te zmiany – na przykład wydać klientowi zakupiony towar –
udostępniamy dwa sposoby synchronizacji:

* **Powiadomienia IPN** – jest to rekomendowana, najszybsza i najbezpieczniejsza metoda. Za każdym razem, gdy
transakcja zmieni swój status, SimPay wyśle automatyczne powiadomienie (żądanie POST) na skonfigurowany
przez Ciebie adres URL.
Szczegóły dotyczące struktury tych powiadomień oraz eventów znajdziesz w sekcji:
**[Zmiana statusu transakcji](/notifications/payment/events/transaction_status_changed)**.
* **Weryfikacja przez API (Polling)** – w dowolnym momencie możesz również samodzielnie pobrać aktualny status
konkretnej operacji, wysyłając zapytanie bezpośrednio do naszego API.
Dokładny opis endpointu służącego do sprawdzania statusu znajdziesz tutaj:
**[Status transakcji](/apis/payment/paymentgettransaction)**.


Dobra praktyka
Zalecamy opieranie logiki biznesowej (np. realizacji zamówień) przede wszystkim na powiadomieniach IPN. Odpytywanie
API (polling) powinno służyć jedynie jako mechanizm awaryjny (fallback) lub do jednorazowego upewnienia się o statusie
przed podjęciem kluczowych akcji.

Statusy zwrotów
Podobnie jak w przypadku samych transakcji, proces zwrotu środków (refundacji) posiada własny, uproszczony cykl życia.
Śledzenie tych statusów pozwala na weryfikację, czy środki zostały już pomyślnie odesłane na konto klienta, czy też
wystąpił problem po drodze.

Poniższy diagram prezentuje możliwe przejścia między poszczególnymi etapami zwrotu:

## Cykl życia zwrotu

### Opis poszczególnych statusów zwrotów

Poniższa tabela szczegółowo wyjaśnia znaczenie każdego ze statusów pojawiających się w kontekście operacji zwrotu (
`RefundStatus`):

| Status (`enum`) | Typ | Opis |
|  --- | --- | --- |
| `refund_new` | **Procesowany** | Zwrot został pomyślnie utworzony w systemie i oczekuje na przekazanie do realizacji. |
| `refund_pending` | **Procesowany** | Żądanie zwrotu zostało wysłane do operatora płatności lub banku. Operacja jest w trakcie wykonywania. |
| `refund_completed` | **Sukces** | Finalny status pozytywny. Zwrot został pomyślnie dokonany, a środki wracają na konto płatnika. |
| `refund_rejected` | **Błąd** | Żądanie zwrotu zostało odrzucone (np. przez bank lub z powodu braku wystarczającego salda na koncie sklepu). |
| `refund_failed` | **Błąd** | Wystąpił techniczny błąd podczas próby wykonania zwrotu (np. błąd w komunikacji z zewnętrznym API). Proces został przerwany. |


Warto wiedzieć
Status `refund_completed` oznacza, że SimPay z sukcesem przeprocesował zwrot. Należy jednak pamiętać, że czas
księgowania środków na rachunku bankowym klienta zależy od jego banku lub wystawcy karty.

## Jak zostajesz informowany o zmianach statusu?

Zmiany statusów transakcji oraz zwrotów zachodzą w naszym systemie asynchronicznie (np. po zatwierdzeniu płatności przez
bank). Aby Twoja aplikacja mogła natychmiast zareagować na te zmiany – na przykład wydać klientowi zakupiony towar –
udostępniamy dwa sposoby synchronizacji:

* **Powiadomienia IPN** – jest to rekomendowana, najszybsza i najbezpieczniejsza metoda. Za każdym razem, gdy
transakcja lub zwrot zmieni swój status, SimPay wyśle automatyczne powiadomienie (żądanie POST) na skonfigurowany
przez Ciebie adres URL.
Szczegóły dotyczące struktury tych powiadomień oraz eventów znajdziesz w sekcji:
**[Zmiana statusu zwrotu](/notifications/payment/events/transaction_refund_status_changed)**.
* **Weryfikacja przez API (Polling)** – w dowolnym momencie możesz również samodzielnie pobrać aktualny status
konkretnej operacji, wysyłając zapytanie bezpośrednio do naszego API.
Dokładny opis endpointu służącego do sprawdzania statusu znajdziesz tutaj:
**[Status zwrotu](/apis/payment/paymenttransactionrefundshow)**.


Dobra praktyka
Zalecamy opieranie logiki biznesowej (np. realizacji zamówień) przede wszystkim na powiadomieniach IPN. Odpytywanie
API (polling) powinno służyć jedynie jako mechanizm awaryjny (fallback) lub do jednorazowego upewnienia się o statusie
przed podjęciem kluczowych akcji.

Statusy aliasów BLIK
Rejestracja i zarządzanie powiązanymi aliasami BLIK odbywa się w sposób asynchroniczny. Śledzenie statusu aliasu pozwala
określić, czy klient może już dokonywać szybkich płatności (tzw. **OneClick** - alias `UID`) lub czy możesz automatycznie obciążać
jego rachunek w ramach płatności powtarzalnych (**Subskrypcje** - alias `PAYID`), bez konieczności każdorazowego przepisywania
sześciocyfrowego kodu z aplikacji bankowej.

Poniższy diagram prezentuje cykl życia aliasu w naszym systemie:

## Cykl życia aliasu BLIK

### Opis poszczególnych statusów

Poniższa tabela szczegółowo wyjaśnia znaczenie każdego ze statusów pojawiających się w cyklu życia aliasu BLIK (
`AliasStatus`):

| Status (`enum`) | Typ | Opis |
|  --- | --- | --- |
| `alias_pending_registration` | **Procesowany** | Alias został zainicjowany w systemie i oczekuje na zatwierdzenie (rejestrację) przez kupującego w aplikacji mobilnej jego banku. |
| `alias_active` | **Aktywny** | Alias został pomyślnie zarejestrowany. Możesz go używać do inicjowania szybkich płatności (OneClick) oraz realizowania płatności powtarzalnych (Subskrypcje). |
| `alias_expired` | **Zakończony** | Aktywny alias wygasł. Należy poprosić klienta o ponowną rejestrację. |
| `alias_unregistered` | **Zakończony** | Kupujący wyrejestrował alias w aplikacji mobilnej banku lub w Panelu Billingowym SimPay. |


### Jak zostajesz informowany o zmianach statusu?

Podobnie jak w przypadku standardowych transakcji, cykl życia aliasów opiera się na zdarzeniach zależnych od akcji
klienta. Aby Twoja aplikacja na bieżąco wiedziała, czy dany alias jest już aktywny lub czy nie został wyrejestrowany,
udostępniamy dwie metody synchronizacji:

* **Powiadomienia IPN** – jest to rekomendowana, najszybsza i najbezpieczniejsza metoda. Za każdym razem, gdy
transakcja lub zwrot zmieni swój status, SimPay wyśle automatyczne powiadomienie (żądanie POST) na skonfigurowany
przez Ciebie adres URL.
Szczegóły dotyczące struktury tych powiadomień oraz eventów znajdziesz w sekcji:
**[Zmiana statusu aliasu BLIK](/notifications/payment/events/blik_alias_status_changed)**.
* **Weryfikacja przez API (Polling)** – w dowolnym momencie możesz również samodzielnie pobrać aktualny status
konkretnej operacji, wysyłając zapytanie bezpośrednio do naszego API.
Dokładny opis endpointu służącego do sprawdzania statusu znajdziesz tutaj:
**[Status aliasu BLIK](/apis/payment/paymentblikaliasesindex)**.


Dobra praktyka
Zalecamy opieranie logiki biznesowej (np. realizacji zamówień) przede wszystkim na powiadomieniach IPN. Odpytywanie
API (polling) powinno służyć jedynie jako mechanizm awaryjny (fallback) lub do jednorazowego upewnienia się o statusie
przed podjęciem kluczowych akcji.

Statusy subskrypcji
System subskrypcji pozwala na cykliczne, automatyczne obciążanie wybranej metody płatności klienta. Każda subskrypcja
przechodzi przez swój cykl życia – od momentu jej utworzenia i autoryzacji, poprzez okres aktywności, aż po jej
zakończenie (naturalne, anulowanie lub wygaśnięcie np. z powodu braku środków).

Poniższy diagram przedstawia możliwe przejścia pomiędzy statusami subskrypcji:

## Cykl życia subskrypcji

Poniższa tabela szczegółowo wyjaśnia znaczenie każdego ze statusów pojawiających się w cyklu życia płatności
powtarzalnych (`SubscriptionStatus`):

| Status (`enum`) | Typ | Opis |
|  --- | --- | --- |
| `subscription_pending` | **Procesowany** | Subskrypcja została utworzona w systemie i oczekuje na autoryzację metody płatności przez klienta. Brak możliwości pobierania środków. |
| `subscription_active` | **Aktywny** | Subskrypcja została poprawnie aktywowana. Można dokonywać cyklicznych obciążeń zgodnie z ustawionym harmonogramem. |
| `subscription_cancelled` | **Zakończony** | Subskrypcja została anulowana przez klienta, sklep lub nie udało się jej poprawnie aktywować. Dalsze obciążenia nie będą realizowane. |
| `subscription_expired` | **Wygaśnięcie** | Aktywna subskrypcja wygasła (np. z powodu utraty ważności metody płatności). |
| `subscription_finished` | **Zakończony pomyślnie** | Cykl subskrypcji dobiegł końca zgodnie z pierwotnym planem/harmonogramem zamówienia. |
| `subscription_fraudulent` | **Błąd krytyczny** | Subskrypcja została oznaczona jako oszustwo (np. chargeback lub użycie kradzionych danych). Proces zostaje natychmiast zablokowany. |


### Jak zostajesz informowany o zmianach statusu?

Ponieważ subskrypcje to procesy długoterminowe (odnawiające się np. co miesiąc), kluczowe jest zautomatyzowanie
odbierania informacji o ich stanie. Udostępniamy dwie metody synchronizacji danych:

* **Powiadomienia IPN** – to absolutnie rekomendowana metoda przy obsłudze płatności powtarzalnych. Gdy subskrypcja
zmieni status (np. wygaśnie lub pomyślnie pobierze kolejną ratę), SimPay wyśle żądanie POST do Twojej aplikacji.
Szczegóły dotyczące struktury tych powiadomień oraz eventów znajdziesz w sekcji:
**[Zmiana statusu subskrypcji](/notifications/payment/events/subscription_status_changed)**.
* **Weryfikacja przez API (Polling)** – w dowolnym momencie możesz również samodzielnie pobrać aktualny status
konkretnej operacji, wysyłając zapytanie bezpośrednio do naszego API.
Dokładny opis endpointu służącego do sprawdzania statusu znajdziesz tutaj:
**[Status subskrypcji](/apis/payment/paymentsubscriptionindex)**.


Dobra praktyka
Zalecamy opieranie logiki biznesowej (np. realizacji zamówień) przede wszystkim na powiadomieniach IPN. Odpytywanie
API (polling) powinno służyć jedynie jako mechanizm awaryjny (fallback) lub do jednorazowego upewnienia się o statusie
przed podjęciem kluczowych akcji.