Verification Systems

Overview

AcqMarketplace implements a dual verification system to ensure both financial compliance and platform trust:

1. Stripe KYC - Financial verification for payments and payouts
2. Platform Verification - Identity and legitimacy verification

Stripe KYC System

Purpose

• Financial Compliance: Required for receiving payouts from Stripe
• Regulatory Requirements: Meets financial service regulations
• Payment Processing: Enables automated payment processing

Implementation

• Provider: Stripe Connect
• Status Tracking: kyc_status field in profiles
• Values: not_started, pending, submitted, complete, restricted
• Payout Control: payouts_enabled boolean flag

User Flow

1. User navigates to /seller-verification
2. Clicks "Complete Stripe KYC" button
3. Redirected to Stripe Connect onboarding
4. Completes identity verification with Stripe
5. Returns to platform with updated status

Admin Management

• Location: /admin/seller-verifications
• Actions: View KYC status, refresh status, manage payouts
• Monitoring: Track verification progress and issues

Platform Verification System

Purpose

• Identity Verification: Verify user identity and legitimacy
• Trust Building: Increase marketplace trust and safety
• Content Quality: Ensure authentic business listings
• Fraud Prevention: Reduce fake accounts and listings

Implementation

• Status Tracking: seller_verification_status field in profiles
• Values: unverified, pending, approved, rejected
• Verification Date: seller_verification_date timestamp
• Verified Flag: seller_verified boolean

User Flow

1. User navigates to /profile-verification
2. Uploads required documents (ID, business proof, etc.)
3. Submits verification request
4. Admin reviews documents
5. Admin approves/rejects with feedback
6. User receives notification of decision

Admin Management

• Location: /admin/profile-verifications
• Actions: Review documents, approve/reject, add notes
• Document Storage: Private bucket with signed URLs
• Audit Trail: Track verification history and decisions

Integration in Transaction Flow

Verification Flow Diagram

graph TD
    A[User Registration] --> B{Verification Required?}
    B -->|Yes| C[Platform Verification]
    B -->|Yes| D[Stripe KYC]
    
    C --> E[Upload Documents]
    E --> F[Admin Review]
    F --> G{Approved?}
    G -->|Yes| H[Platform Verified]
    G -->|No| I[Rejected - Fix Required]
    I --> E
    
    D --> J[Stripe Connect Onboarding]
    J --> K[Stripe KYC Process]
    K --> L{KYC Complete?}
    L -->|Yes| M[Stripe KYC Verified]
    L -->|No| N[KYC Pending]
    
    H --> O[Can Create Public Listings]
    M --> P[Can Receive Payouts]
    
    O --> Q[Full Platform Access]
    P --> Q
    
    Q --> R[Transaction Ready]
    R --> S[Deal Processing]
    S --> T[Payout Release]

Deal Requirements

Both verification systems are required for certain transaction phases:

Phase 1: Pre-Transaction Verification

// Platform Verification (required for all deals)
const sellerProfileVerified = profile.seller_verification_status === 'approved';
const buyerProfileVerified = profile.seller_verification_status === 'approved';

// Stripe KYC (required for Stripe payouts)
const sellerKycComplete = profile.kyc_status === 'complete' || profile.payouts_enabled;
const buyerKycComplete = profile.kyc_status === 'complete' || profile.payouts_enabled;

Phase 2: Payout Authorization

// Both verifications required for payout release
const canReleasePayout = 
  sellerProfileVerified && 
  sellerKycComplete && 
  deal.status === 'buyer_accepts';

UI Integration

Transaction History Page

• Stripe KYC Alert: Shows when KYC is pending for payouts
• Platform Verification: Shows verification status in deal checklist
• Combined Status: Clear indication of what's required

Deal Checklist Panel

const platformItems = [
  {
    id: 'platform-buyer-profile',
    label: 'Buyer Profile Verification',
    required: true,
    completed: buyerProfileStatus === 'approved',
    category: 'platform_verification'
  },
  {
    id: 'platform-seller-profile', 
    label: 'Seller Profile Verification',
    required: true,
    completed: sellerProfileStatus === 'approved',
    category: 'platform_verification'
  },
  {
    id: 'platform-buyer-kyc',
    label: 'Buyer KYC Verification',
    required: true,
    completed: buyerKycStatus === 'complete',
    category: 'platform_verification'
  },
  {
    id: 'platform-seller-kyc',
    label: 'Seller KYC Verification', 
    required: true,
    completed: sellerKycStatus === 'complete',
    category: 'platform_verification'
  }
];

Verification Status Matrix

User Type	Platform Verification	Stripe KYC	Can Create Listings	Can Receive Payouts	Can Make Offers
Unverified	❌	❌	✅ (draft only)	❌	✅
Platform Only	✅	❌	✅ (public)	❌	✅
Stripe Only	❌	✅	✅ (draft only)	✅	✅
Fully Verified	✅	✅	✅ (public)	✅	✅

Data Model

Profiles Table

CREATE TABLE profiles (
  id UUID PRIMARY KEY,
  -- Platform Verification
  seller_verified BOOLEAN DEFAULT FALSE,
  seller_verification_status TEXT CHECK (seller_verification_status IN ('unverified', 'pending', 'approved', 'rejected')),
  seller_verification_date TIMESTAMPTZ,
  
  -- Stripe KYC
  kyc_status TEXT CHECK (kyc_status IN ('not_started', 'pending', 'submitted', 'complete', 'restricted')),
  payouts_enabled BOOLEAN DEFAULT FALSE,
  details_submitted BOOLEAN DEFAULT FALSE,
  
  -- Other fields...
);

Seller Verifications Table

CREATE TABLE seller_verifications (
  id UUID PRIMARY KEY,
  seller_id UUID REFERENCES profiles(id),
  document_type TEXT NOT NULL,
  document_url TEXT NOT NULL,
  status TEXT CHECK (status IN ('pending', 'approved', 'rejected')),
  submitted_at TIMESTAMPTZ DEFAULT NOW(),
  verified_at TIMESTAMPTZ,
  verified_by UUID REFERENCES profiles(id),
  notes TEXT
);

Edge Functions

Stripe KYC Management

• connect-onboarding-link: Generate Stripe Connect onboarding URL
• connect-dashboard-link: Generate Stripe dashboard URL
• refresh-kyc-status: Sync KYC status from Stripe

Platform Verification

• send-seller-verification-notification: Notify admin of new verification requests
• send-verification-status-update: Notify user of verification decision

Notifications

User Notifications

• Verification Submitted: Confirmation when documents uploaded
• Verification Approved: Success notification with next steps
• Verification Rejected: Feedback on what needs to be fixed
• KYC Required: Alert when KYC needed for payouts

Admin Notifications

• New Verification Request: Alert when user submits documents
• KYC Status Change: Notification when Stripe status updates
• Verification Overdue: Reminder for pending verifications

Security & Privacy

Document Storage

• Bucket: seller-verifications (private)
• Access: Signed URLs with expiration
• Retention: Documents kept for audit purposes
• Encryption: At rest and in transit

Data Protection

• RLS Policies: Users can only access their own verification data
• Admin Access: Restricted to admin role only
• Audit Logging: All verification actions logged
• GDPR Compliance: Right to deletion and data portability

Best Practices

For Users

1. Complete Both Verifications: Required for full platform access
2. Keep Documents Current: Update expired documents promptly
3. Follow Guidelines: Ensure documents meet platform requirements
4. Monitor Status: Check verification status regularly

For Admins

1. Review Promptly: Process verification requests within 24-48 hours
2. Provide Feedback: Give clear reasons for rejections
3. Monitor Compliance: Track verification completion rates
4. Maintain Security: Follow document handling procedures

For Developers

1. Check Both Statuses: Always verify both platform and KYC status
2. Handle Edge Cases: Account for partial verification states
3. Update UI Dynamically: Show current verification status
4. Log Verification Events: Track all verification-related actions

Troubleshooting

Common Issues

KYC Status Not Updating

• Cause: Stripe webhook not received
• Solution: Use refresh-kyc-status function
• Prevention: Monitor webhook delivery in Stripe dashboard

Platform Verification Stuck

• Cause: Admin not processing requests
• Solution: Check admin queue, send reminder
• Prevention: Set up automated reminders

Document Upload Fails

• Cause: File size/type restrictions
• Solution: Check file requirements, compress if needed
• Prevention: Client-side validation before upload

Status Sync Issues

• Stripe KYC: Use refresh function to sync latest status
• Platform Verification: Check admin processing queue
• Combined Status: Verify both systems independently

Future Enhancements

Planned Features

1. Automated Document Verification: AI-powered document validation
2. Biometric Verification: Enhanced identity verification
3. International KYC: Support for multiple jurisdictions
4. Verification Analytics: Detailed verification metrics and insights

Integration Improvements

1. Single Verification Flow: Combined platform and KYC process
2. Status Dashboard: Unified verification status view
3. Mobile Verification: Mobile-optimized verification process
4. API Integration: Third-party verification service integration

---

Related Documentation:

• Seller Verification - Platform verification details
• Stripe Integration - Stripe KYC implementation
• Deals & Transactions - Verification in transaction flow
• Security & Privacy - Verification security measures