KYC Status Lifecycle (Profile)

This document defines the state machine for the KYC status of a Profile. It governs the identity verification process, ensuring a clear and auditable trail from initiation to a final approved or declined state.

Lifecycle Diagram

The KYC lifecycle is a straightforward process with a clear path for success, failure, and retries.

Flow:new → pending → approvednew → pending → declined → new (Retry Loop)

Status Definitions

Status	Description
new	The default internal status assigned to a Profile before the KYC process is initiated.
pending	The identity verification attempt is underway. The system is awaiting completion of all steps by the user or final confirmation from the provider (Plaid).
approved	✅ The user has successfully passed all identity verification checks and meets the required standards.
declined	❌ The user failed one or more verification steps and will be advised to contact support or retry.

Key Transitions

• Initiate Verification (new → pending)

  • Trigger: The user starts the identity verification flow.

  • Action: The system changes the status to pending.

• Approve Verification (pending → approved)

  • Trigger: The system receives a success webhook from the KYC provider.

  • Action: The system updates the status to approved, sets the kyc_at timestamp, and unlocks investment capabilities for the profile.

• Decline Verification (pending → declined)

  • Trigger: The system receives a failed webhook from the KYC provider.

  • Action: The system updates the status to declined and logs the reason for failure.

• Retry Verification (declined → new)

  • Trigger: An admin user re-initiates the identity verification flow for the profile with declined KYC status.

  • Action: The system changes the status back to new for the new verification attempt.