Funding Status Lifecycle (Investment)

This document defines the wire-value state machine for the funding_status field on an Investment. The transition path is scoped to the payment rail because wallet completion and escrow release do not share the same trigger.

Lifecycle Diagram

The escrow rail has a path to confirmed release. The wallet API has a separate path that records settled when its wallet transfer completes.

Escrow release path:

new → initialize → in_progress → received → settled

received records receipt in escrow. For this rail only, settled records the confirmed post-close release from escrow to the issuer.

Wallet API completion path:

initialize → in_progress → settled

The wallet API records the lowercase wire value settled when its investment transfer completes. That path does not apply an Offer close condition.

Alternative Paths:

• (Creation) → creation_error (Initial Failure)

• initialize / in_progress → canceled

• in_progress → failed

• received → sent_back_pending → sent_back_settled (Escrow Refund Path)

State Definitions

Status	Description
creation_error	The initial attempt to create the transfer with the payment provider failed.
new	The investment funding record was created before provider initialization.
initialize	The transfer was created with the provider and awaits processing.
in_progress	The transfer is actively being processed by the payment provider's network.
received	For the escrow rail, funds arrived in escrow and await release to the issuer.
settled	For escrow, the confirmed post-close release reached the issuer. The wallet API also uses this value for a completed wallet transfer without an Offer-close check.
sent_back_pending	An escrow refund transfer was created to return funds to the investor.
sent_back_settled	The escrow refund was confirmed and funds returned to the investor's original account.
failed	The transfer failed for a terminal reason, such as insufficient funds or an invalid bank account.
canceled	The transfer was cancelled before completion.

Key Transitions

• Create Transfer (new → initialize or creation_error)

  • Trigger: The parent Investment status moves to LEGALLY_CONFIRMED.

  • Action: The system attempts to create a transfer with the payment provider. On success, the status is set to initialize. If the initial API call fails, the status is set to creation_error.

• Begin Processing (initialize → in_progress)

  • Trigger: The payment provider signals that they have begun processing the transaction.

  • Action: The system updates the status to in_progress based on a provider webhook or API response.

• Confirm Escrow Receipt (in_progress → received)

  • Trigger: A webhook from the payment provider confirms funds have arrived in the "smart escrow" account.

  • Action: The status is updated to received. The investment is funded in escrow, but the issuer has not received the release.

• Release Escrow Funds (received → settled)

  • Trigger: The parent Offer reaches closed_successfully, and an administrator triggers the release from the escrow account.

  • Action: The system instructs the provider to move funds to the issuer. On confirmation, the escrow-rail status is updated to settled.

• Complete Wallet Transfer (in_progress → settled)

  • Trigger: The wallet API receives the transfer-complete webhook for an investment transaction.

  • Action: The wallet worker records the lowercase settled funding status when the wallet transfer completes. This transition does not require closed_successfully.

• Handle Failure (in_progress → failed)

  • Trigger: A webhook from the provider indicates a terminal failure (e.g., Returned for ACH).

  • Action: The status is updated to failed, and the user and administrator are notified.

• Initiate Refund (received → sent_back_pending)

  • Trigger: The parent Investment is cancelled after escrow funds were received but before they are settled.

  • Action: The system initiates a refund transfer. The status is updated to sent_back_pending while that transfer is pending.

• Confirm Refund (sent_back_pending → sent_back_settled)

  • Trigger: A webhook from the provider confirms the refund transaction has been successfully processed.

  • Action: The status is updated to sent_back_settled.