Wallet Status Lifecycle

This document defines the state machine for the status field of a Wallet. It governs the wallet's verification process with the third-party provider, tracking it from the initial creation request to a fully operational or suspended state.

Lifecycle Diagram

The lifecycle has a direct path to verification, but includes several loops to handle cases where the provider requires additional user information or documentation.

Primary Flow: (KYC Approved) → created → verified

Alternative (Error & Resolution) Paths:

• created → error_retry → error_pending → verified

• created → error_document → error_pending → verified

• error_pending → error_suspended (Terminal Failure)

State Definitions

Status	Description
created	An API request to create the Wallet has been successfully sent to the provider. Awaiting initial verification.
error	The initial API request to create the Wallet failed. Requires technical investigation.
verified	The wallet is fully verified by the provider and is operational for sending and receiving funds.
error_retry	The provider requires additional or corrected personal information from the user to complete verification.
error_document	The provider requires the user to upload identity documents (e.g., passport, driver's license) for verification.
error_pending	The user has submitted the requested info/documents and the Wallet is pending manual review by the provider.
error_suspended	The provider has refused to verify the Wallet after review. The wallet cannot be used.

Key Transitions

• Create Wallet (... → created or error)

  • Trigger: The associated Profile's kyc_status changes to approved.

  • Action: The system makes an API call to the provider to create a new customer and funding source. On a successful call, the status becomes created. If the call fails, the status becomes error.

• Verify Wallet (created → verified)

  • Trigger: The system receives a webhook from the provider indicating the wallet was successfully verified on the first attempt.

  • Action: The status is updated to verified. The user is notified that their wallet is active.

• Handle Verification Issues (created → error_retry / error_document)

  • Trigger: The system receives a webhook from the provider with a status of retry or document.

  • Action: The status is updated accordingly. The user is notified and presented with a flow to submit the required information or documents.

• Submit Additional Info (error_retry / error_document → error_pending)

  • Trigger: The user successfully submits the required additional data or documents.

  • Action: The system sends the new information to the provider via API and updates the wallet status to error_pending.

• Resolve Pending Review (error_pending → verified or error_suspended)

  • Trigger: The system receives a final status webhook from the provider after their manual review.

  • Action: The status is updated to verified if approved, or error_suspended if ultimately rejected. The user is notified of the outcome.