# Statuses in SimPay

Select the type of statuses you are interested in to learn more about their meaning and use in our system.

Transaction Statuses
Every transaction in the SimPay system has its own lifecycle, represented by appropriate statuses. A status change informs about the current stage of payment processing – from the moment of initiation to successful completion, rejection, or refund.

The following diagram shows the possible transition paths between individual transaction statuses in our API.

## Transaction Lifecycle

## Description of Individual Statuses

In our API responses, the transaction status is returned as a string. The following table explains the meaning of each:

| Status (`enum`) | Type | Description |
|  --- | --- | --- |
| `transaction_new` | **Processing** | Initial status after creating a new transaction in the system. Payment awaits further steps. |
| `transaction_generated` | **Processing** | The customer selected a payment method and proceeded to pay |
| `transaction_confirmed` | **Processing** | The payment method informed us about the initiation of payment processing. |
| `transaction_paid` | **Success** | Payment was successfully completed and funds have been secured. This is the main status of a successful transaction. You can proceed to fulfill the order |
| `transaction_failure` | **Error** | Payment was rejected (e.g., insufficient funds, authorization denied by bank, 3D Secure error). |
| `transaction_expired` | **Error / Expiration** | The time allocated for paying the transaction has elapsed. The payment path is irreversibly closed. |
| `transaction_refunded` | **Refund** | A successful full refund (100% of the amount) was made to the payer's account. |
| `transaction_fraud_possibility` | **Verification** | The system detected an anomaly or risk. The transaction requires additional verification before final approval or rejection. |
| `transaction_fraud` | **Critical Error** | The transaction was flagged as fraud (e.g., stolen card, chargeback). Funds will not be transferred. |


Integration Tip
The `transaction_paid` status is the only status indicating correct and final payment of the order by the customer (unless a refund occurs later).
Your application should fulfill the order (deliver goods/services) only after receiving a webhook with this status.

## How Are You Informed About Status Changes?

Transaction and refund status changes occur asynchronously in our system (e.g., after bank payment approval). For your application to react immediately to these changes – for example, to deliver purchased goods to the customer – we provide two synchronization methods:

* **IPN Notifications** – this is the recommended, fastest, and most secure method. Every time a transaction changes its status, SimPay will send an automatic notification (POST request) to the URL you configured.
Details about the structure of these notifications and events can be found in the section:
**[Transaction Status Change](/notifications/payment/events/transaction_status_changed)**.
* **API Verification (Polling)** – at any time, you can also independently retrieve the current status of a specific operation by sending a query directly to our API.
The exact endpoint description for checking the status can be found here:
**[Transaction Status](/apis/payment/paymentgettransaction)**.


Best Practice
We recommend basing your business logic (e.g., order fulfillment) primarily on IPN notifications. API polling should serve only as a fallback mechanism or for one-time status verification before taking critical actions.

Refund Statuses
Similar to transactions themselves, the refund process has its own simplified lifecycle. Tracking these statuses allows you to verify whether funds have already been successfully sent back to the customer's account, or if a problem occurred along the way.

The following diagram shows the possible transitions between individual refund stages:

## Refund Lifecycle

### Description of Individual Refund Statuses

The following table explains the meaning of each status appearing in the context of refund operations (`RefundStatus`):

| Status (`enum`) | Type | Description |
|  --- | --- | --- |
| `refund_new` | **Processing** | The refund was successfully created in the system and awaits processing. |
| `refund_pending` | **Processing** | The refund request was sent to the payment operator or bank. The operation is in progress. |
| `refund_completed` | **Success** | Final positive status. The refund was successfully completed, and funds are being returned to the payer's account. |
| `refund_rejected` | **Error** | The refund request was rejected (e.g., by the bank or due to insufficient balance in the store's account). |
| `refund_failed` | **Error** | A technical error occurred during the refund attempt (e.g., error in communication with external API). Process was aborted. |


Good to Know
The `refund_completed` status means that SimPay successfully processed the refund. However, keep in mind that the time for funds to appear in the customer's bank account depends on their bank or card issuer.

## How Are You Informed About Status Changes?

Transaction and refund status changes occur asynchronously in our system (e.g., after bank payment approval). For your application to react immediately to these changes – for example, to deliver purchased goods to the customer – we provide two synchronization methods:

* **IPN Notifications** – this is the recommended, fastest, and most secure method. Every time a transaction or refund changes its status, SimPay will send an automatic notification (POST request) to the URL you configured.
Details about the structure of these notifications and events can be found in the section:
**[Refund Status Change](/notifications/payment/events/transaction_refund_status_changed)**.
* **API Verification (Polling)** – at any time, you can also independently retrieve the current status of a specific operation by sending a query directly to our API.
The exact endpoint description for checking the status can be found here:
**[Refund Status](/apis/payment/paymenttransactionrefundshow)**.


Best Practice
We recommend basing your business logic (e.g., order fulfillment) primarily on IPN notifications. API polling should serve only as a fallback mechanism or for one-time status verification before taking critical actions.

BLIK Alias Statuses
Registration and management of linked BLIK aliases is done asynchronously. Tracking the alias status allows you to determine whether the customer can already make quick payments (so-called **OneClick** - alias `UID`) or whether you can automatically charge their account as part of recurrent payments (**Subscriptions** - alias `PAYID`), without the need to enter the six-digit code from the banking app each time.

The following diagram shows the alias lifecycle in our system:

## BLIK Alias Lifecycle

### Description of Individual Statuses

The following table explains the meaning of each status appearing in the BLIK alias lifecycle (`AliasStatus`):

| Status (`enum`) | Type | Description |
|  --- | --- | --- |
| `alias_pending_registration` | **Processing** | The alias was initiated in the system and awaits approval (registration) by the buyer in their mobile banking app. |
| `alias_active` | **Active** | The alias was successfully registered. You can use it to initiate quick payments (OneClick) and execute recurrent payments (Subscriptions). |
| `alias_expired` | **Terminated** | The active alias has expired. You should ask the customer to re-register. |
| `alias_unregistered` | **Terminated** | The buyer deregistered the alias in their mobile banking app or in the SimPay Billing Panel. |


### How Are You Informed About Status Changes?

Similar to standard transactions, the alias lifecycle is based on events dependent on customer actions. For your application to know in real time whether a given alias is already active or has been deregistered, we provide two synchronization methods:

* **IPN Notifications** – this is the recommended, fastest, and most secure method. Every time a transaction or refund changes its status, SimPay will send an automatic notification (POST request) to the URL you configured.
Details about the structure of these notifications and events can be found in the section:
**[BLIK Alias Status Change](/notifications/payment/events/blik_alias_status_changed)**.
* **API Verification (Polling)** – at any time, you can also independently retrieve the current status of a specific operation by sending a query directly to our API.
The exact endpoint description for checking the status can be found here:
**[BLIK Alias Status](/apis/payment/paymentblikaliasesindex)**.


Best Practice
We recommend basing your business logic (e.g., order fulfillment) primarily on IPN notifications. API polling should serve only as a fallback mechanism or for one-time status verification before taking critical actions.

Subscription Statuses
The subscription system allows for cyclical, automatic charging of the customer's selected payment method. Each subscription goes through its lifecycle – from the moment of creation and authorization, through the period of activity, to its completion (natural, cancellation, or expiration e.g., due to insufficient funds).

The following diagram shows the possible transitions between subscription statuses:

## Subscription Lifecycle

The following table explains the meaning of each status appearing in the recurrent payment lifecycle (`SubscriptionStatus`):

| Status (`enum`) | Type | Description |
|  --- | --- | --- |
| `subscription_pending` | **Processing** | The subscription was created in the system and awaits payment method authorization by the customer. No fund collection possible. |
| `subscription_active` | **Active** | The subscription was successfully activated. Cyclical charges can be made according to the set schedule. |
| `subscription_cancelled` | **Terminated** | The subscription was cancelled by the customer, store, or failed to activate properly. No further charges will be made. |
| `subscription_expired` | **Expiration** | The active subscription has expired (e.g., due to loss of payment method validity). |
| `subscription_finished` | **Successfully Completed** | The subscription cycle has ended according to the original plan/order schedule. |
| `subscription_fraudulent` | **Critical Error** | The subscription was flagged as fraud (e.g., chargeback or use of stolen data). The process is immediately blocked. |


### How Are You Informed About Status Changes?

Since subscriptions are long-term processes (renewing e.g., monthly), it is crucial to automate receiving information about their status. We provide two data synchronization methods:

* **IPN Notifications** – this is the absolutely recommended method for handling recurrent payments. When a subscription changes status (e.g., expires or successfully collects the next installment), SimPay will send a POST request to your application.
Details about the structure of these notifications and events can be found in the section:
**[Subscription Status Change](/notifications/payment/events/subscription_status_changed)**.
* **API Verification (Polling)** – at any time, you can also independently retrieve the current status of a specific operation by sending a query directly to our API.
The exact endpoint description for checking the status can be found here:
**[Subscription Status](/apis/payment/paymentsubscriptionindex)**.


Best Practice
We recommend basing your business logic (e.g., order fulfillment) primarily on IPN notifications. API polling should serve only as a fallback mechanism or for one-time status verification before taking critical actions.