User Onboarding Flow

Complete user journey from anonymous visitor to fully verified platform user.

Overview

The onboarding flow consists of several stages:

1. Region selection (geo-detection with confirmation)
2. Anonymous visit with referral attribution
3. Registration and email verification (regional account)
4. Profile completion
5. KYC verification (required for investments, NOT for shop purchases)

Regional Account Model

• One account per region - User registers once and can access invest, shop, and partner platforms within that region
• Regional SSO - Single sign-on across all platforms within the region
• Regional KYC - KYC completed on Invest platform is valid for all regional platforms
• Cross-region isolation - Different regions require separate accounts (for regulatory compliance)

KYC Requirements by Platform

Platform	KYC Required	Notes
Invest	Yes	Required before making investments
Shop	No	Can browse and purchase without KYC
Partner	No	Required only for payouts

---

Main Flow Diagram

---

Step Details

0. Region Selection

Trigger: User visits the main domain (iwm.com)

Geo-Detection:

• System detects user's location via IP geolocation
• Determines appropriate regional platform (EU, US, APAC)

Region Confirmation Modal:

• Shows detected region with option to change
• User can select a different region if needed
• Selection is stored in cookie for future visits

Available Regions:

Region	Domain	Data Residency	Regulations
EU	eu.iwm.com	Europe	GDPR, MiFID II
US	us.iwm.com	United States	SEC, FinCEN
APAC	apac.iwm.com	Singapore	MAS

After Selection:

• User is redirected to the regional platform
• All subsequent interactions occur within that region
• Account created will be regional

---

1. Anonymous Visit

Trigger: User lands on the platform via referral link or direct visit.

Referral Link Format:

https://platform.com/?ref=ABC123&utm_source=instagram&utm_medium=post&utm_campaign=summer

Cookie Storage:

Key	Value	Duration
iwm_ref_code	Partner referral code	30 days
iwm_ref_link_id	Specific link ID (if tracked)	30 days
iwm_first_touch	First visit timestamp	30 days
iwm_utm	JSON with UTM params	Session

Attribution Data Stored:

{
  "partner_code": "ABC123",
  "link_id": "uuid-of-link",
  "first_touch_at": "2024-01-15T10:30:00Z",
  "last_touch_at": "2024-01-15T10:30:00Z",
  "utm_source": "instagram",
  "utm_medium": "post",
  "utm_campaign": "summer",
  "landing_page": "/products",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0..."
}

---

2. Registration

Endpoint: POST /auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "SecureP@ss123",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+7900123456",
  "acceptTerms": true,
  "acceptMarketing": false
}

Validation Rules:

Field	Rules
email	Required, valid email format, unique in DB
password	Min 8 chars, 1 uppercase, 1 lowercase, 1 number, 1 special
firstName	Required, 2-100 chars, letters only
lastName	Required, 2-100 chars, letters only
phone	Optional, E.164 format
acceptTerms	Required, must be true

Error Scenarios:

Code	Scenario	Response
400	Validation failed	{ "errors": [...] }
409	Email exists	{ "code": "EMAIL_EXISTS" }
429	Rate limit exceeded	Retry-After header

---

3. Email Verification

Verification Token:

• Format: UUID v4
• Expiry: 24 hours
• Single use (deleted after verification)

Verification Email Content:

• Subject: "Verify your email - IWM Platform"
• Link: https://platform.com/verify?token={token}
• Includes: User name, expiry notice, support contact

Resend Logic:

• Max 3 resends per hour
• New token generated each time
• Previous tokens invalidated

Timeout Handling:

• Token expires after 24 hours
• User can request new token
• Account auto-deleted after 7 days if unverified

---

4. Profile Completion

Endpoint: PATCH /users/me/profile

Optional Fields:

{
  "middleName": "Ivanovich",
  "dateOfBirth": "1990-05-15",
  "avatarUrl": "https://cdn.example.com/avatar.jpg",
  "countryCode": "RU",
  "region": "Moscow Oblast",
  "city": "Moscow",
  "postalCode": "101000",
  "addressLine1": "ul. Tverskaya, 1",
  "language": "ru",
  "timezone": "Europe/Moscow",
  "currency": "USD"
}

Avatar Upload:

• Endpoint: POST /users/me/avatar
• Max size: 5MB
• Formats: JPEG, PNG, WebP
• Resized to: 200x200, 400x400

---

5. KYC Submission

KYC Levels:

Level	Requirements	Capabilities
NONE	Default	Browse, basic purchases
BASIC	Email verified	All purchases
STANDARD	ID + Selfie verified	Investments up to $100,000
ENHANCED	Address proof + Income proof	Unlimited investments

Required Documents (STANDARD):

Document	Accepted Types
ID Document	Passport, National ID, Driver's License
Selfie	Photo with ID visible

Document Upload:

• Endpoint: POST /kyc/documents
• Max size: 10MB per file
• Formats: JPEG, PNG, PDF
• Encrypted at rest (AES-256)

Validation Rules:

• Document must be legible
• Selfie must clearly show face and ID
• ID not expired
• Name matches profile

---

6. KYC Review Process

Status Flow:

NOT_STARTED -> DOCUMENTS_PENDING -> SUBMITTED -> UNDER_REVIEW -> APPROVED/REJECTED/NEEDS_INFO

Review Timeline:

• Standard: 24-48 business hours
• Priority (large investments): 4-8 hours

Rejection Reasons:

Code	Description	User Action
DOCUMENT_BLURRY	Document not readable	Re-upload clearer image
DOCUMENT_EXPIRED	ID has expired	Upload valid ID
SELFIE_MISMATCH	Face doesn't match ID	Retake selfie
INFO_MISMATCH	Details don't match profile	Update profile or upload correct docs
SUSPECTED_FRAUD	Suspicious activity	Contact support

Re-submission:

• Max 3 attempts per document type
• After 3 failures, manual review required
• Cool-down: 24 hours between submissions

---

Error Scenarios

Registration Errors

Scenario	HTTP Code	Error Code	User Message
Email already registered	409	EMAIL_EXISTS	"This email is already registered. Try logging in."
Weak password	400	WEAK_PASSWORD	"Password does not meet requirements."
Invalid email format	400	INVALID_EMAIL	"Please enter a valid email address."
Terms not accepted	400	TERMS_REQUIRED	"You must accept the terms to continue."
Rate limited	429	RATE_LIMITED	"Too many attempts. Please wait."

Verification Errors

Scenario	HTTP Code	Error Code	User Message
Token expired	400	TOKEN_EXPIRED	"This link has expired. Request a new one."
Token already used	400	TOKEN_USED	"This link has already been used."
Token not found	404	TOKEN_NOT_FOUND	"Invalid verification link."

KYC Errors

Scenario	HTTP Code	Error Code	User Message
File too large	413	FILE_TOO_LARGE	"File exceeds 10MB limit."
Invalid file type	400	INVALID_FILE_TYPE	"Please upload JPEG, PNG, or PDF."
KYC already approved	400	ALREADY_VERIFIED	"Your identity has already been verified."
Max attempts exceeded	400	MAX_ATTEMPTS	"Please contact support for assistance."

---

Related Documents

• Architecture Overview
• Core Schema (Users, KYC)
• Auth Flow Diagram
• Partner Journey
• Security Standards