Status Lifecycles
Every status enum, valid transitions, and terminal states for all entities.
PaymentSession
PENDING
PAYMENT_IN_PROGRESS
AWAITING_VERIFICATION
COMPLETED
FAILED
EXPIRED
Transitions
| From | To | Trigger |
|---|---|---|
PENDING |
PAYMENT_IN_PROGRESS |
/pay endpoint, atomic select_for_update |
PAYMENT_IN_PROGRESS |
COMPLETED |
Gateway approved (Vendo status=1) |
PAYMENT_IN_PROGRESS |
AWAITING_VERIFICATION |
Gateway status=2 (mandate signing required) |
PAYMENT_IN_PROGRESS |
PENDING |
Gateway decline, retries remaining |
PAYMENT_IN_PROGRESS |
FAILED |
Gateway decline, max attempts reached |
AWAITING_VERIFICATION |
COMPLETED |
Verification success |
AWAITING_VERIFICATION |
PENDING |
Verification failed, retries remaining |
AWAITING_VERIFICATION |
FAILED |
Verification failed, max attempts reached |
PENDING |
EXPIRED |
Cancel endpoint |
Terminal States
COMPLETED, FAILED, EXPIRED -- no transitions out.
Order
PENDING_PAYMENT_SUBMISSION
PENDING
COMPLETED
FAILED
PARTIALLY_REFUNDED
REFUNDED
CHARGEDBACK
CANCELLED
Status Descriptions
| Status | Description |
|---|---|
PENDING_PAYMENT_SUBMISSION |
Order exists but payment not yet submitted to gateway. Default on creation. |
PENDING |
Payment submitted, awaiting settlement. |
COMPLETED |
First successful transaction received. |
FAILED |
Payment permanently failed. |
PARTIALLY_REFUNDED |
Partial refund processed. |
REFUNDED |
Full refund processed. |
CHARGEDBACK |
Chargeback received. |
CANCELLED |
Order cancelled. |
Subscription
PENDING_ACTIVATION
ACTIVE
PENDING
PAST_DUE
PAUSED
CANCELLED
EXPIRED
CHARGEDBACK
FAILED
Status Descriptions
| Status | Description |
|---|---|
PENDING_ACTIVATION |
Subscription created, awaiting first successful charge. |
ACTIVE |
Active and billing normally. |
PENDING |
Pending first payment. |
PAST_DUE |
Missed one or more billing cycles. |
PAUSED |
Billing temporarily paused. |
CANCELLED |
Cancelled by customer or admin. |
EXPIRED |
Natural expiration. |
CHARGEDBACK |
Chargeback received on this subscription. |
FAILED |
Permanently failed (unrecoverable). |
Cancellable Statuses
Subscriptions in these statuses can be cancelled:
ACTIVE, PENDING_ACTIVATION, PENDING, PAST_DUE, PAUSED
Terminal Statuses (Subscription)
These statuses cannot be cancelled or reactivated:
CANCELLED, EXPIRED, CHARGEDBACK
Terminal Subscription Guard
Subscriptions in CANCELLED, EXPIRED, or CHARGEDBACK status ignore approved transaction signals. This prevents late-arriving settlement CSVs from reactivating dead subscriptions.
Exception: charged_back transactions can override CANCELLED (fraud takes priority over churn).
Transaction
Transaction statuses use snake_case (technical/ledger statuses mapped from adapters).
approved
declined
pending_async
pending_hold
pending
error
refunded
cancelled
charged_back
voided
chargeback_reversed
represented
representment_reversed
second_chargeback
pending_review
partially_reversed
other_status
pending_payment_submission
Transaction Types
sdd_sale
sdd_refund
other_type
Protected Statuses (Nuclear States)
These statuses cannot be overwritten by transaction CSV imports:
charged_back
second_chargeback
representment_reversed
Only ChargebackImportService can set these statuses. Regular settlement CSVs are blocked from changing transactions in these states.
Transaction Source
How a transaction was created:
csv_import
api_submission
admin_refund
webhook
hosted_page
Chargeback
Chargeback Statuses
charged_back
Chargeback Types
chargeback
Chargeback Source
How a chargeback was created:
csv_import
webhook
reconciliation
manual
Lead
LEAD
ACTIVE_CUSTOMER
CHURNED
CHARGEDBACK
Status Priority (Cascade Rules)
Status is computed by StatusCascadeService, not set manually:
| Status | Condition | Priority |
|---|---|---|
CHARGEDBACK |
Any chargeback exists | Highest |
ACTIVE_CUSTOMER |
Any non-terminal subscription OR standalone completed order | -- |
CHURNED |
Only terminal subscriptions (CANCELLED/EXPIRED) remain | -- |
LEAD |
No payment history | Default |
Registration Mode
How a lead was created:
WEB_FORM
CSV_IMPORT
API
HOSTED_PAGE