Transaction Status Lifecycle

This document defines the state machine for the status field of a Transaction. It governs the lifecycle of a single financial event from initiation to its final state.

Lifecycle Diagram

The transaction lifecycle is simple, with a single pending state that can resolve to one of three terminal states.

Flow:PENDING → PROCESSED (Success) PENDING → FAILED (Failure) PENDING → CANCELLED (Cancellation)

State Definitions

Status	Description
PENDING	The transaction has been initiated but is not yet confirmed or settled by the payment provider.
PROCESSED	The transaction was successful, and funds have been settled in the destination account.
FAILED	The transaction failed and was not completed.
CANCELLED	The transaction was cancelled while it was PENDING and was not processed.

Key Transitions

• Complete Transaction (PENDING → PROCESSED)

  • Trigger: The system receives a success confirmation from the payment provider.

  • Action: The status is updated to COMPLETED, wallet balances are finalized, and the completed_at timestamp is set.

• Fail Transaction (PENDING → FAILED)

  • Trigger: The system receives a failure confirmation from the payment provider.

  • Action: The status is updated to FAILED, any reserved funds are released, and the completed_at timestamp is set.

• Cancel Transaction (PENDING → CANCELLED)

  • Trigger: A user or administrator initiates a cancellation for an eligible transaction (DEPOSIT or WITHDRAWAL).

  • Action: The system sends a cancellation request to the provider. On confirmation, the status is updated to CANCELLED.