Transaction Status Lifecycle

This document defines the wire-value state machine for the status field of a Transaction. It governs a wallet transaction from its local intent through provider submission and its terminal state.

Lifecycle Diagram

The wallet API uses separate paths for provider-backed deposit or withdrawal transfers and investment reservations.

Provider-backed deposit or withdrawal flow:created → pending → processed (success)

created → pending → failed (failure)

pending → cancelled (cancellation)

Wallet-funded investment flow:wait → created → pending → processed or failed

State Definitions

Status	Description
created	The local transaction record exists and the provider submission has not yet been recorded.
wait	An investment or linked direct-deposit intent has reserved a balance and is waiting for the funding path to initialize.
pending	The provider has accepted the transfer for processing, but no terminal outcome has been recorded.
processed	The provider confirmed success, and the wallet balance and reservation ledger have been finalized.
failed	The transfer reached a terminal failure outcome.
cancelled	The transfer was cancelled while it was pending and did not process.

Key Transitions

• Initialize Reserved Intent (wait → created)

  • Trigger: A wallet-funded investment or linked direct-deposit intent becomes eligible for provider submission.

  • Action: The wallet API changes the reserved transaction to created before calling the provider.

• Submit Transfer (created → pending)

  • Trigger: The wallet API records the provider response after submitting a deposit or withdrawal transfer.

  • Action: The provider transaction identifier and current provider status are saved. A withdrawal reserves out_balance; a deposit reserves inc_balance.

• Complete Transaction (pending → processed)

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

  • Action: The status is updated to processed, wallet balances are finalized, pending reservations are released, 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 inc_balance or out_balance is released, and the completed_at timestamp is set.

• Cancel Transaction (pending → cancelled)

  • Trigger: A user or administrator initiates a cancellation for an eligible deposit or withdrawal transaction.

  • Action: The system sends a cancellation request to the provider. On confirmation, the status is updated to cancelled and any pending balance reservation is released.