Funding Status Lifecycle (Investment)

This document defines the state machine for the funding_status field on an Investment. This lifecycle tracks the granular, real-time status of the payment transaction itself, from its creation with a third-party provider to its final settlement, failure, or refund.

Lifecycle Diagram

The funding lifecycle has a primary path to successful settlement, as well as distinct paths for failures, cancellations, and refunds.

Primary Success Path (Happy Path):

INITIALIZE → IN_PROGRESS → RECEIVED → SETTLED

Alternative Paths:

• (Creation) → CREATION_ERROR (Initial Failure)

• INITIALIZE / IN_PROGRESS → CANCELLED

• IN_PROGRESS → FAILED

• RECEIVED → SENT_BACK_PENDING → SENT_BACK_SETTLED (Refund Path)

State Definitions

Status	Description
CREATION_ERROR	The initial attempt to create the transfer with the payment provider failed. Requires investigation.
INITIALIZE	The transfer has been successfully created with the provider and is awaiting processing.
IN_PROGRESS	The transfer is actively being processed by the payment provider's network (e.g., ACH network).
RECEIVED	The funds have successfully arrived in the escrow account but have not yet been released to the issuer.
SETTLED	The investment is fully paid. Funds have been cleared and released from escrow to the issuer's account.
SENT_BACK_PENDING	A refund transfer has been created to return funds to the investor.
SENT_BACK_SETTLED	The refund has been successfully processed and the funds have been returned to the investor's original account.
FAILED	The transfer failed for a clear reason, such as insufficient funds or an invalid bank account.
CANCELLED	The transfer was cancelled either by an administrator or the payment provider before completion.

Key Transitions

• Create Transfer (... → 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 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 now considered "funded" from a compliance perspective.

• Settle Funds (RECEIVED → SETTLED)

  • Trigger: The parent Offer successfully closes, and an administrator triggers the release of funds from "smart escrow" account.

  • Action: The system instructs the provider to move funds to the issuer. On confirmation, the status is updated to SETTLED.

• 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 funds were RECEIVED but before being SETTLED.

  • Action: The system initiates a refund transfer. On success, the status is updated to SENT_BACK_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.