Skip to content

domain.enums.transaction_status

src.domain.enums.transaction_status

Transaction status enumeration.

Defines the lifecycle states for financial transactions.

Classes

TransactionStatus

Bases: str, Enum

Transaction lifecycle status.

Represents the current state of a transaction in its lifecycle. All transactions start as PENDING and typically move to SETTLED.

Lifecycle Flow: PENDING → SETTLED (normal flow) PENDING → FAILED (sync/processing error) PENDING → CANCELLED (voided by provider) SETTLED → CANCELLED (rare: reversal after settlement)

Terminal States: SETTLED, FAILED, CANCELLED (no further state changes) Active States: PENDING (may change state)

Provider Mappings: - Schwab API: Maps "status" field directly - Chase: Posted → SETTLED, Pending → PENDING

Source code in src/domain/enums/transaction_status.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class TransactionStatus(str, Enum):
    """Transaction lifecycle status.

    Represents the current state of a transaction in its lifecycle.
    All transactions start as PENDING and typically move to SETTLED.

    **Lifecycle Flow**:
        PENDING → SETTLED (normal flow)
        PENDING → FAILED (sync/processing error)
        PENDING → CANCELLED (voided by provider)
        SETTLED → CANCELLED (rare: reversal after settlement)

    **Terminal States**: SETTLED, FAILED, CANCELLED (no further state changes)
    **Active States**: PENDING (may change state)

    **Provider Mappings**:
        - Schwab API: Maps "status" field directly
        - Chase: Posted → SETTLED, Pending → PENDING
    """

    PENDING = "pending"
    """Transaction is pending settlement.

    Common for:
    - Recent trades (T+0 to T+2 settlement period)
    - ACH transfers (1-3 business days)
    - Pending deposits/withdrawals
    - Unposted credit card transactions

    **Actions**: May still be cancelled or modified by provider
    """

    SETTLED = "settled"
    """Transaction has completed and settled.

    Characteristics:
    - Funds have cleared and are available
    - Cannot be cancelled (except rare reversals)
    - Included in account balance calculations
    - Used for historical reporting

    **Actions**: Immutable (except rare provider-initiated reversals)
    """

    FAILED = "failed"
    """Transaction failed during processing.

    Common causes:
    - Insufficient funds
    - Invalid account details
    - Provider API sync errors
    - System validation failures
    - Network timeouts during sync

    **Actions**: Terminal state, no further changes
    """

    CANCELLED = "cancelled"
    """Transaction was cancelled/voided.

    Common scenarios:
    - User-initiated cancellation (before settlement)
    - Provider-initiated reversal
    - Duplicate transaction correction
    - Fraud prevention

    **Actions**: Terminal state, no further changes
    """

    @classmethod
    def terminal_states(cls) -> list["TransactionStatus"]:
        """Return statuses that represent final states.

        Terminal states indicate the transaction will not change state again
        (except in rare reversal scenarios for SETTLED).

        Returns:
            List containing SETTLED, FAILED, and CANCELLED.

        Example:
            >>> if transaction.status in TransactionStatus.terminal_states():
            ...     # Safe to use in financial reports
        """
        return [cls.SETTLED, cls.FAILED, cls.CANCELLED]

    @classmethod
    def active_states(cls) -> list["TransactionStatus"]:
        """Return statuses that may still change.

        Active states indicate the transaction may transition to another state.

        Returns:
            List containing only PENDING.

        Example:
            >>> if transaction.status in TransactionStatus.active_states():
            ...     # Check for updates from provider
        """
        return [cls.PENDING]
Attributes
PENDING class-attribute instance-attribute 
PENDING = 'pending'

Transaction is pending settlement.

Common for: - Recent trades (T+0 to T+2 settlement period) - ACH transfers (1-3 business days) - Pending deposits/withdrawals - Unposted credit card transactions

Actions: May still be cancelled or modified by provider

SETTLED class-attribute instance-attribute 
SETTLED = 'settled'

Transaction has completed and settled.

Characteristics: - Funds have cleared and are available - Cannot be cancelled (except rare reversals) - Included in account balance calculations - Used for historical reporting

Actions: Immutable (except rare provider-initiated reversals)

FAILED class-attribute instance-attribute 
FAILED = 'failed'

Transaction failed during processing.

Common causes: - Insufficient funds - Invalid account details - Provider API sync errors - System validation failures - Network timeouts during sync

Actions: Terminal state, no further changes

CANCELLED class-attribute instance-attribute 
CANCELLED = 'cancelled'

Transaction was cancelled/voided.

Common scenarios: - User-initiated cancellation (before settlement) - Provider-initiated reversal - Duplicate transaction correction - Fraud prevention

Actions: Terminal state, no further changes

Functions
terminal_states classmethod 
terminal_states() -> list[TransactionStatus]

Return statuses that represent final states.

Terminal states indicate the transaction will not change state again (except in rare reversal scenarios for SETTLED).

Returns:

Type Description
list[TransactionStatus]

List containing SETTLED, FAILED, and CANCELLED.
Example

if transaction.status in TransactionStatus.terminal_states(): ... # Safe to use in financial reports

Source code in src/domain/enums/transaction_status.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@classmethod
def terminal_states(cls) -> list["TransactionStatus"]:
    """Return statuses that represent final states.

    Terminal states indicate the transaction will not change state again
    (except in rare reversal scenarios for SETTLED).

    Returns:
        List containing SETTLED, FAILED, and CANCELLED.

    Example:
        >>> if transaction.status in TransactionStatus.terminal_states():
        ...     # Safe to use in financial reports
    """
    return [cls.SETTLED, cls.FAILED, cls.CANCELLED]
active_states classmethod 
active_states() -> list[TransactionStatus]

Return statuses that may still change.

Active states indicate the transaction may transition to another state.

Returns:

Type Description
list[TransactionStatus]

List containing only PENDING.
Example

if transaction.status in TransactionStatus.active_states(): ... # Check for updates from provider

Source code in src/domain/enums/transaction_status.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
@classmethod
def active_states(cls) -> list["TransactionStatus"]:
    """Return statuses that may still change.

    Active states indicate the transaction may transition to another state.

    Returns:
        List containing only PENDING.

    Example:
        >>> if transaction.status in TransactionStatus.active_states():
        ...     # Check for updates from provider
    """
    return [cls.PENDING]