# Transaction lifecycle & statuses

Status values match the API schema exactly (case-sensitive). `status` is the top-level state; `statusReason.detailedStatus` gives the specific reason.

## Pay-in statuses

| Status | Final? | Meaning |
|  --- | --- | --- |
| `CREATED` | No | Created, not yet processing. |
| `PENDING` | No | Processing; awaiting a result. |
| `PENDING_3DS` | No | Awaiting 3DS authentication. |
| `SUCCESS` | Yes | Payment succeeded. |
| `DECLINED` | Yes | Declined by the provider. |
| `FAILED` | Yes | Processing failed. |
| `TIMEOUT` | Yes* | No final response in time. **A late provider callback can still move it to `SUCCESS`** — see below. |
| `REFUND_PENDING` | No | Refund in progress. |
| `REFUNDED` | Yes | Fully refunded. |
| `PARTIALLY_REFUNDED` | Yes | Partially refunded. |
| `REFUND_FAILED` | Yes | Refund attempt failed. |


```mermaid
stateDiagram-v2
    [*] --> CREATED
    CREATED --> PENDING
    CREATED --> PENDING_3DS
    PENDING_3DS --> PENDING
    PENDING --> SUCCESS
    PENDING --> DECLINED
    PENDING --> FAILED
    PENDING --> TIMEOUT
    TIMEOUT --> SUCCESS: late provider callback
    SUCCESS --> REFUND_PENDING
    REFUND_PENDING --> REFUNDED
    REFUND_PENDING --> PARTIALLY_REFUNDED
    REFUND_PENDING --> REFUND_FAILED
    SUCCESS --> [*]
    DECLINED --> [*]
    FAILED --> [*]
```

> ⚠️ **The `TIMEOUT → SUCCESS` rule.** A pay-in that timed out can later become `SUCCESS` if the provider sends a late callback. Your webhook handler must accept this upgrade and must never treat `TIMEOUT` as a permanent failure. This is the one exception to "never change a final status."


## Payout statuses

| Status | Final? | Meaning |
|  --- | --- | --- |
| `CREATED` | No | Created, not yet processing. |
| `WAITING_FOR_CONFIRMATION` | No | Awaiting manual [confirm/reject](/guides/concepts/payouts). |
| `PENDING` | No | Processing; awaiting a result. |
| `PROCESSED` | Yes | Payout completed. |
| `REJECTED` | Yes | Rejected; never sent to a provider. |
| `FAILED` | Yes | Processing failed. |
| `TIMEOUT` | Yes* | No final response in time. |


```mermaid
stateDiagram-v2
    [*] --> CREATED
    CREATED --> WAITING_FOR_CONFIRMATION
    CREATED --> PENDING
    WAITING_FOR_CONFIRMATION --> PENDING: confirm
    WAITING_FOR_CONFIRMATION --> REJECTED: reject
    PENDING --> PROCESSED
    PENDING --> FAILED
    PENDING --> TIMEOUT
    PROCESSED --> [*]
    REJECTED --> [*]
    FAILED --> [*]
```

## Pay-in `detailedStatus`

| Value | Meaning |
|  --- | --- |
| `GENERAL_DECLINE` | Generic decline with no specific reason. |
| `BANK_ISSUES` | Issuing bank problem. |
| `PSP_ISSUES` | Provider-side problem. |
| `CUSTOMER_ISSUES` | Customer-side problem. |
| `CVV_INVALID` | Invalid CVV. |
| `CARD_EXPIRED` | Card expired. |
| `CARD_BLOCKED` | Card blocked. |
| `CARD_NOT_SUPPORTED` | Card type not supported. |
| `NO_PROVIDER_AVAILABLE` | No provider eligible/available to process. |
| `OTHER` | Other reason. |
| `PROVIDER_NOT_SUITABLE` | No suitable provider for this transaction. |
| `PROVIDER_NOT_IN_ROUTE` | Provider not part of the route. |
| `FRAUD_SCORE_ABOVE_THRESHOLD` | Fraud score exceeded the threshold. |
| `BLACKLISTED` | Customer/card blacklisted. |
| `BLOCKED_CARD` | Card blocked. |
| `BLOCKED_CUSTOMER` | Customer blocked. |
| `INVALID_CREDENTIALS` | Invalid provider credentials. |
| `AUTHENTICATION_FAILED` | Authentication failed. |
| `ACCESS_DENIED` | Access denied by the provider. |
| `CARD_DECLINED` | Card declined by the issuer. |
| `TRANSACTION_NOT_ALLOWED` | Transaction not allowed. |
| `VALIDATION_ERROR` | Request validation failed. |
| `INVALID_CARD_NUMBER` | Invalid card number. |
| `INVALID_EXPIRY_DATE` | Invalid expiry date. |
| `CVV_MISMATCH` | CVV mismatch. |
| `SYSTEM_ERROR` | Internal system error. |
| `DUPLICATE_TRANSACTION` | Duplicate transaction detected. |
| `MARKED_AS_FRAUD` | Marked as fraud. |
| `PSP_UNREACHABLE` | Provider could not be reached. |
| `INVALID_REQUEST_FORMAT` | Malformed request to the provider. |
| `OTHER_FAILURES` | Other failure. |
| `UNMAPPED_ERRORS` | Error not mapped to a known reason. |
| `INSUFFICIENT_FUNDS` | Insufficient funds. |
| `THREE_DS_NOT_SUPPORTED` | 3DS not supported. |
| `TRANSACTION_TIMEOUT` | Transaction timed out. |
| `REFUND_ERROR` | Refund error. |
| `REFUND_ALREADY_PROCESSED` | Refund already processed. |
| `PARTIAL_REFUND_NOT_ALLOWED` | Partial refund not allowed. |


## Payout `detailedStatus`

| Value | Meaning |
|  --- | --- |
| `NO_PROVIDER_AVAILABLE` | No provider eligible/available to process. |
| `AMOUNT_TOO_LOW` | Amount below the allowed minimum. |
| `AMOUNT_TOO_HIGH` | Amount above the allowed maximum. |
| `OTHER` | Other reason. |
| `PROVIDER_NOT_SUITABLE` | No suitable provider for this transaction. |
| `PROVIDER_NOT_IN_ROUTE` | Provider not part of the route. |
| `FRAUD_SCORE_ABOVE_THRESHOLD` | Fraud score exceeded the threshold. |
| `BLACKLISTED` | Customer/card blacklisted. |
| `BLOCKED_CARD` | Card blocked. |
| `BLOCKED_CUSTOMER` | Customer blocked. |
| `REJECTED_BY_MERCHANT` | Rejected via the reject endpoint. |
| `PSP_CHANGED_AFTER_APPROVAL` | Provider changed after approval. |
| `INVALID_CREDENTIALS` | Invalid provider credentials. |
| `AUTHENTICATION_FAILED` | Authentication failed. |
| `ACCESS_DENIED` | Access denied by the provider. |
| `CARD_DECLINED` | Card declined by the issuer. |
| `TRANSACTION_NOT_ALLOWED` | Transaction not allowed. |
| `VALIDATION_ERROR` | Request validation failed. |
| `INVALID_CARD_NUMBER` | Invalid card number. |
| `INVALID_EXPIRY_DATE` | Invalid expiry date. |
| `CVV_MISMATCH` | CVV mismatch. |
| `SYSTEM_ERROR` | Internal system error. |
| `DUPLICATE_TRANSACTION` | Duplicate transaction detected. |
| `MARKED_AS_FRAUD` | Marked as fraud. |
| `PSP_UNREACHABLE` | Provider could not be reached. |
| `INVALID_REQUEST_FORMAT` | Malformed request to the provider. |
| `OTHER_FAILURES` | Other failure. |
| `UNMAPPED_ERRORS` | Error not mapped to a known reason. |
| `INSUFFICIENT_FUNDS` | Insufficient funds. |
| `TRANSACTION_REJECTED_BY_PROVIDER` | Rejected by the provider. |


## Build it →

- [Webhooks](/guides/concepts/webhooks) · [Payouts & manual approval](/guides/concepts/payouts)