Business LogicKYC Architecture

KYC Architecture

Overview

Wafra implements a unified, provider-agnostic KYC system that abstracts compliance verification across multiple payment providers. The system provides a consistent user experience while meeting global regulatory requirements.

KYC Providers

Onramp Money

  • Purpose: Primary fiat-to-crypto payment provider
  • Method: Traditional document verification (ID + selfie + address proof)
  • Integration: Direct REST API
  • Status: ✅ Active

DTR (Digital Treasury Receipt)

  • Purpose: Enhanced compliance with crypto-native authentication
  • Method: SIWE (Sign-In-With-Ethereum) + Sumsub verification
  • Integration: Whitelabel solution with webhook support
  • Status: ✅ Active

Provider Selection

KYC provider is automatically determined by:

  1. Payment Method Choice - Selected payment provider drives KYC provider
  2. Rate Optimization - Best exchange rates influence provider selection
  3. Regulatory Requirements - Compliance needs override rate considerations

System Architecture

Unified KYC Service

All providers implement a standardized interface for consistent user experience:

interface KYCProvider {
  getRequirements(user: User): Promise<KYCRequirements>;
  submitKYC(user: User, data: KYCData): Promise<KYCResult>;
  getStatus(user: User): Promise<KYCStatus>;
  uploadDocument(user: User, document: Document): Promise<UploadResult>;
}

High-Level Flow

Provider-Specific Flows

Onramp KYC Flow

Required Documents:

  • Government-issued ID (passport, driver’s license, national ID)
  • Selfie photograph
  • Utility bill or bank statement (address proof)

DTR KYC Flow

Features:

  • Crypto-native authentication via wallet signature
  • Enhanced compliance with Sumsub integration
  • Real-time liveness detection
  • Ongoing AML/sanctions monitoring

Document Management

Secure Upload Process:

Security Features:

  • Encryption: AES-256 encryption at rest
  • Storage: MinIO (S3-compatible) with randomized file names
  • Validation: File type, size (10MB limit), malware scanning
  • Retention: Latest document only, automatic deletion of previous versions

Status Management

KYC Status Lifecycle

Status Mapping:

  • DTR: KYC_NEEDED → PENDING → FULL_USER → APPROVED
  • Onramp: LOGIN_REQUIRED → KYC_PENDING → APPROVED

Real-time Updates

  • Webhook Integration: Provider status changes trigger immediate updates
  • tRPC Subscriptions: Frontend receives real-time status notifications
  • Email Notifications: Users informed of status changes and next steps

Data Management

Form Generation & Prefill

Intelligent Prefill Sources:

  • User Profile: Name, email, phone from registration
  • Previous KYC: Reuse verified data across providers
  • Address Data: Consistent formatting and validation
  • Document Reuse: Latest uploads available for new submissions

Cross-Provider Benefits

  • Reduced Friction: Minimal re-entry when switching providers
  • Data Consistency: Standardized information across all flows
  • Faster Processing: Pre-validated data accelerates approval

Technical Implementation

Database Schema

API Integration

tRPC Endpoints:

  • kyc.getStatus() - Unified status across providers
  • kyc.getRequirements() - Dynamic form generation with prefill
  • kyc.submitKycDetails() - Standardized submission
  • kyc.uploadDocument() - Secure document handling

Security & Compliance

Data Protection

  • Encryption: AES-256 for all sensitive data at rest
  • Access Controls: Role-based access with audit logging
  • Retention Policies: Automated deletion per regulatory requirements
  • GDPR Compliance: Data minimization and user rights support

Regulatory Coverage

  • US: FINCEN, BSA, OFAC sanctions screening
  • EU: GDPR, AMLD5 compliance
  • UK: FCA, MLR 2017 requirements
  • Global: Real-time AML/sanctions monitoring

Monitoring & Analytics

Key Metrics:

  • Provider completion rates and processing times
  • Document rejection reasons and resubmission patterns
  • Geographic and demographic approval trends
  • Compliance audit trails and regulatory reporting

Future Enhancements

Planned Improvements

  • Enhanced Document AI: Automatic data extraction from uploaded documents
  • Biometric Verification: Advanced liveness detection and facial recognition
  • Risk Scoring: ML-based user risk assessment and dynamic requirements
  • Multi-Language Support: Localized KYC flows for global expansion

Long-Term Vision

  • Decentralized Identity: Self-sovereign identity integration with verifiable credentials
  • Cross-Platform KYC: Reusable verified credentials across DeFi platforms
  • Continuous Monitoring: Ongoing compliance verification and risk assessment
  • Regulatory Automation: Automated reporting and compliance management

This simplified KYC architecture provides a robust foundation for multi-provider compliance while maintaining excellent user experience and strong security practices.

Payment ProvidersReferrals System