Setting Up Stablecoin KYC Verification: Identity Provider Integration Guide

// Jumio SDK integration example
const jumioClient = new JumioClient({
  apiToken: process.env.JUMIO_API_TOKEN,
  apiSecret: process.env.JUMIO_API_SECRET,
  baseUrl: 'https://netverify.com/api/v4'
});

const initiateVerification = async (userId) => {
  try {
    const verification = await jumioClient.createVerification({
      customerInternalReference: userId,
      userReference: `user_${userId}`,
      reportingCriteria: 'KYC_STABLECOIN_PLATFORM',
      callback: `${process.env.BASE_URL}/webhooks/jumio/callback`,
      successUrl: `${process.env.FRONTEND_URL}/verification/success`,
      errorUrl: `${process.env.FRONTEND_URL}/verification/error`
    });
    
    return verification.redirectUrl;
  } catch (error) {
    console.error('Jumio verification failed:', error);
    throw new Error('Identity verification initiation failed');
  }
};

// Onfido SDK setup
const onfido = require('@onfido/api-client');

const onfidoClient = new onfido.DefaultApi(
  new onfido.Configuration({
    apiKey: process.env.ONFIDO_API_TOKEN,
    region: onfido.Region.US // or EU based on your jurisdiction
  })
);

const createApplicant = async (userInfo) => {
  try {
    const applicant = await onfidoClient.createApplicant({
      first_name: userInfo.firstName,
      last_name: userInfo.lastName,
      email: userInfo.email,
      address: {
        street: userInfo.address.street,
        town: userInfo.address.city,
        postcode: userInfo.address.zipCode,
        country: userInfo.address.country
      }
    });
    
    return applicant.data.id;
  } catch (error) {
    console.error('Onfido applicant creation failed:', error);
    throw error;
  }
};

// Shufti Pro integration
const axios = require('axios');

const shuftiProVerification = async (userData) => {
  const verificationRequest = {
    reference: `stablecoin_${userData.userId}`,
    country: userData.country,
    language: 'en',
    email: userData.email,
    callback_url: `${process.env.BASE_URL}/webhooks/shuftipro/callback`,
    services: {
      document: {
        proof: '',
        additional_proof: '',
        name: {
          first_name: userData.firstName,
          last_name: userData.lastName
        },
        dob: userData.dateOfBirth,
        document_type: ['passport', 'id_card', 'driving_license'],
        supported_types: ['jpg', 'jpeg', 'png', 'pdf']
      },
      face: {
        proof: ''
      },
      address: {
        proof: '',
        full_address: userData.fullAddress,
        supported_types: ['jpg', 'jpeg', 'png', 'pdf']
      }
    }
  };

  try {
    const response = await axios.post(
      'https://api.shuftipro.com/',
      verificationRequest,
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Basic ${Buffer.from(
            `${process.env.SHUFTI_CLIENT_ID}:${process.env.SHUFTI_SECRET_KEY}`
          ).toString('base64')}`
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Shufti Pro verification failed:', error);
    throw error;
  }
};

-- KYC verification tracking table
CREATE TABLE kyc_verifications (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id),
    provider VARCHAR(50) NOT NULL, -- 'jumio', 'onfido', 'shuftipro'
    provider_reference VARCHAR(255),
    status VARCHAR(50) DEFAULT 'pending', -- pending, in_progress, approved, rejected, expired
    risk_level VARCHAR(20) DEFAULT 'medium', -- low, medium, high
    verification_data JSONB,
    documents_uploaded JSONB,
    compliance_flags JSONB DEFAULT '[]',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    expires_at TIMESTAMP WITH TIME ZONE,
    CONSTRAINT valid_status CHECK (status IN ('pending', 'in_progress', 'approved', 'rejected', 'expired')),
    CONSTRAINT valid_risk_level CHECK (risk_level IN ('low', 'medium', 'high'))
);

-- Sanctions screening results
CREATE TABLE sanctions_screening (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    kyc_verification_id UUID NOT NULL REFERENCES kyc_verifications(id),
    screening_provider VARCHAR(50), -- 'ofac', 'eu_sanctions', 'un_sanctions'
    match_found BOOLEAN DEFAULT FALSE,
    match_details JSONB,
    screening_date TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    manual_review_required BOOLEAN DEFAULT FALSE,
    reviewer_notes TEXT
);

-- Compliance audit trail
CREATE TABLE kyc_audit_trail (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    kyc_verification_id UUID NOT NULL REFERENCES kyc_verifications(id),
    action VARCHAR(100) NOT NULL,
    actor_type VARCHAR(50), -- 'system', 'admin', 'compliance_officer'
    actor_id UUID,
    details JSONB,
    timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

// KYC workflow orchestrator
class KYCWorkflowOrchestrator {
  constructor() {
    this.providers = {
      jumio: new JumioProvider(),
      onfido: new OnfidoProvider(),
      shuftipro: new ShuftiProProvider()
    };
    this.complianceEngine = new ComplianceEngine();
    this.sanctionsScreener = new SanctionsScreener();
  }

  async processKYCVerification(userId, userData) {
    const verificationId = await this.createKYCRecord(userId);
    
    try {
      // Step 1: Risk assessment to choose provider
      const riskLevel = await this.assessInitialRisk(userData);
      const provider = this.selectProvider(riskLevel, userData.country);
      
      // Step 2: Initiate identity verification
      const providerResult = await this.initiateVerification(provider, userData);
      
      // Step 3: Parallel sanctions screening
      const sanctionsResult = await this.screenForSanctions(userData);
      
      // Step 4: Update verification status
      await this.updateVerificationStatus(verificationId, {
        provider: provider,
        provider_reference: providerResult.reference,
        status: 'in_progress',
        sanctions_screening: sanctionsResult
      });
      
      return {
        verificationId,
        provider,
        redirectUrl: providerResult.redirectUrl,
        estimatedProcessingTime: this.getEstimatedTime(provider, riskLevel)
      };
      
    } catch (error) {
      await this.handleVerificationError(verificationId, error);
      throw error;
    }
  }

  async handleProviderCallback(provider, callbackData) {
    const verification = await this.getVerificationByReference(
      provider, 
      callbackData.reference
    );
    
    if (!verification) {
      throw new Error('Verification not found');
    }

    // Process provider results
    const complianceResult = await this.complianceEngine.evaluate({
      providerData: callbackData,
      userRiskProfile: verification.risk_level,
      sanctionsScreening: verification.sanctions_screening
    });

    // Auto-approve, reject, or flag for manual review
    const finalStatus = this.determineFinalStatus(complianceResult);
    
    await this.updateVerificationStatus(verification.id, {
      status: finalStatus,
      verification_data: callbackData,
      compliance_result: complianceResult
    });

    // Trigger post-verification actions
    await this.triggerPostVerificationActions(verification.user_id, finalStatus);
    
    return finalStatus;
  }

  selectProvider(riskLevel, country) {
    // High-risk countries or customers require enhanced verification
    if (riskLevel === 'high' || this.isHighRiskJurisdiction(country)) {
      return 'shuftipro'; // More thorough verification
    }
    
    // EU customers for GDPR compliance
    if (this.isEUCountry(country)) {
      return 'onfido'; // EU data residency
    }
    
    // Standard verification for most users
    return 'jumio';
  }

  async screenForSanctions(userData) {
    const screeningResults = await Promise.all([
      this.sanctionsScreener.checkOFAC(userData),
      this.sanctionsScreener.checkEUSanctions(userData),
      this.sanctionsScreener.checkUNSanctions(userData)
    ]);
    
    return {
      ofac: screeningResults[0],
      eu_sanctions: screeningResults[1],
      un_sanctions: screeningResults[2],
      overall_risk: this.calculateSanctionsRisk(screeningResults)
    };
  }
}

// Continuous compliance monitoring
class ContinuousComplianceMonitor {
  constructor() {
    this.scheduler = new ComplianceScheduler();
    this.riskAnalyzer = new RiskAnalyzer();
    this.alertSystem = new ComplianceAlertSystem();
  }

  async startMonitoring(userId) {
    // Schedule regular sanctions list updates
    await this.scheduler.schedulePeriodicScreening(userId, {
      frequency: 'monthly',
      priority: 'standard'
    });

    // Monitor transaction patterns for suspicious activity
    await this.scheduler.scheduleActivityMonitoring(userId, {
      volumeThreshold: 10000, // USD
      frequencyThreshold: 50, // transactions per day
      geographicRiskAssessment: true
    });

    // Enhanced monitoring for high-risk users
    const userRisk = await this.riskAnalyzer.getCurrentRiskLevel(userId);
    if (userRisk === 'high') {
      await this.scheduleEnhancedMonitoring(userId);
    }
  }

  async processTransactionForCompliance(transaction) {
    const complianceChecks = await Promise.all([
      this.checkTransactionLimits(transaction),
      this.checkTravelRule(transaction),
      this.checkSanctionsCompliance(transaction),
      this.checkAMLPatterns(transaction)
    ]);

    const riskScore = this.calculateTransactionRisk(complianceChecks);
    
    if (riskScore > 0.8) {
      await this.flagForManualReview(transaction, complianceChecks);
      return { approved: false, requiresManualReview: true };
    }

    if (riskScore > 0.6) {
      await this.applyEnhancedMonitoring(transaction.userId);
    }

    return { approved: true, riskScore };
  }

  async checkTravelRule(transaction) {
    // FATF Travel Rule compliance for transactions over $1000
    if (transaction.amount >= 1000) {
      const senderInfo = await this.getCompleteUserInfo(transaction.senderId);
      const recipientInfo = await this.getCompleteUserInfo(transaction.recipientId);
      
      return {
        travelRuleRequired: true,
        senderCompliant: this.validateUserInfo(senderInfo),
        recipientCompliant: this.validateUserInfo(recipientInfo),
        crossBorder: senderInfo.country !== recipientInfo.country
      };
    }
    
    return { travelRuleRequired: false };
  }
}

// Automatic document quality enhancement
const enhanceDocumentQuality = async (documentBuffer) => {
  try {
    // Use Sharp for image processing
    const enhanced = await sharp(documentBuffer)
      .resize(2000, null, { withoutEnlargement: true })
      .sharpen()
      .normalize()
      .png({ quality: 90 })
      .toBuffer();
    
    // OCR confidence check
    const ocrResult = await tesseract.recognize(enhanced, 'eng');
    
    if (ocrResult.data.confidence < 80) {
      throw new Error('Document quality insufficient for OCR processing');
    }
    
    return {
      enhancedDocument: enhanced,
      ocrConfidence: ocrResult.data.confidence,
      extractedText: ocrResult.data.text
    };
    
  } catch (error) {
    console.error('Document enhancement failed:', error);
    throw new Error('Unable to process document - please upload a clearer image');
  }
};

// Appeals handling system
class VerificationAppealsSystem {
  async submitAppeal(verificationId, appealData) {
    const appeal = await db.appeals.create({
      verification_id: verificationId,
      reason: appealData.reason,
      supporting_documents: appealData.documents,
      status: 'pending_review',
      submitted_at: new Date()
    });

    // Auto-escalate high-value customer appeals
    const user = await this.getUserByVerificationId(verificationId);
    if (user.lifetime_volume > 100000) {
      await this.escalateToSeniorCompliance(appeal.id);
    }

    // Notify compliance team
    await this.notifyComplianceTeam(appeal);
    
    return appeal;
  }

  async processAppeal(appealId, reviewerDecision) {
    const appeal = await db.appeals.findById(appealId);
    const originalVerification = await db.kyc_verifications.findById(
      appeal.verification_id
    );

    if (reviewerDecision.approved) {
      // Override original rejection
      await this.updateVerificationStatus(appeal.verification_id, 'approved');
      await this.enableUserAccount(originalVerification.user_id);
    }

    await db.appeals.update(appealId, {
      status: reviewerDecision.approved ? 'approved' : 'rejected',
      reviewer_notes: reviewerDecision.notes,
      reviewed_at: new Date(),
      reviewed_by: reviewerDecision.reviewerId
    });

    // Send notification to user
    await this.notifyUserOfAppealDecision(originalVerification.user_id, reviewerDecision);
  }
}

// Cost-optimized provider selection with failover
class SmartProviderRouter {
  constructor() {
    this.providers = [
      { name: 'jumio', cost: 3.50, successRate: 0.92, avgTime: 15 },
      { name: 'onfido', cost: 2.80, successRate: 0.89, avgTime: 12 },
      { name: 'shuftipro', cost: 4.20, successRate: 0.95, avgTime: 18 }
    ];
  }

  async selectOptimalProvider(userProfile, riskLevel) {
    // Calculate cost-effectiveness score
    const scores = this.providers.map(provider => {
      const riskMultiplier = this.getRiskMultiplier(riskLevel, provider.successRate);
      const geographicFit = this.getGeographicFit(userProfile.country, provider.name);
      
      return {
        ...provider,
        score: (provider.successRate * geographicFit * riskMultiplier) / provider.cost
      };
    });

    // Sort by best score and apply business rules
    const rankedProviders = scores.sort((a, b) => b.score - a.score);
    
    // For high-risk users, prioritize success rate over cost
    if (riskLevel === 'high') {
      return rankedProviders.find(p => p.successRate > 0.9) || rankedProviders[0];
    }

    return rankedProviders[0];
  }

  async executeWithFailover(primaryProvider, fallbackProvider, userData) {
    try {
      const result = await this.providers[primaryProvider].verify(userData);
      
      // Track success for future optimization
      await this.recordProviderPerformance(primaryProvider, 'success', result.processingTime);
      
      return result;
    } catch (error) {
      console.warn(`Primary provider ${primaryProvider} failed, trying fallback`);
      
      try {
        const fallbackResult = await this.providers[fallbackProvider].verify(userData);
        
        // Record both failure and success
        await this.recordProviderPerformance(primaryProvider, 'failure', null);
        await this.recordProviderPerformance(fallbackProvider, 'success', fallbackResult.processingTime);
        
        return fallbackResult;
      } catch (fallbackError) {
        await this.recordProviderPerformance(fallbackProvider, 'failure', null);
        throw new Error('All verification providers failed');
      }
    }
  }
}

// KYC analytics and monitoring
const generateKYCMetrics = async (timeRange) => {
  const metrics = await db.query(`
    WITH verification_stats AS (
      SELECT 
        DATE_TRUNC('day', created_at) as date,
        provider,
        status,
        risk_level,
        COUNT(*) as count,
        AVG(EXTRACT(EPOCH FROM (updated_at - created_at))/60) as avg_processing_minutes
      FROM kyc_verifications 
      WHERE created_at >= $1 AND created_at <= $2
      GROUP BY DATE_TRUNC('day', created_at), provider, status, risk_level
    ),
    cost_analysis AS (
      SELECT 
        provider,
        COUNT(*) as total_verifications,
        SUM(CASE WHEN status = 'approved' THEN 1 ELSE 0 END) as successful_verifications,
        COUNT(*) * (CASE 
          WHEN provider = 'jumio' THEN 3.50
          WHEN provider = 'onfido' THEN 2.80
          WHEN provider = 'shuftipro' THEN 4.20
        END) as total_cost
      FROM kyc_verifications
      WHERE created_at >= $1 AND created_at <= $2
      GROUP BY provider
    )
    SELECT 
      vs.*,
      ca.total_cost,
      ca.successful_verifications::float / ca.total_verifications as success_rate
    FROM verification_stats vs
    LEFT JOIN cost_analysis ca ON vs.provider = ca.provider
    ORDER BY vs.date DESC, vs.provider
  `, [timeRange.start, timeRange.end]);

  return {
    daily_metrics: metrics,
    summary: {
      total_verifications: metrics.reduce((sum, m) => sum + m.count, 0),
      average_success_rate: this.calculateWeightedAverage(metrics, 'success_rate'),
      total_cost: metrics.reduce((sum, m) => sum + (m.total_cost || 0), 0),
      average_processing_time: this.calculateWeightedAverage(metrics, 'avg_processing_minutes')
    }
  };
};

// Automated regulatory reporting
class RegulatoryReportGenerator {
  async generateSARReport(suspiciousActivity) {
    const report = {
      reporting_period: this.getCurrentReportingPeriod(),
      financial_institution: {
        name: process.env.COMPANY_NAME,
        ein: process.env.COMPANY_EIN,
        address: process.env.COMPANY_ADDRESS
      },
      suspicious_activities: await this.compileSuspiciousActivities(suspiciousActivity),
      compliance_officer: await this.getComplianceOfficerInfo()
    };

    // Generate FinCEN BSA E-Filing format
    const finCENReport = await this.convertToFinCENFormat(report);
    
    // Store for audit trail
    await this.storeReport('SAR', finCENReport);
    
    return finCENReport;
  }

  async generateKYCAuditReport(auditPeriod) {
    const auditData = await db.query(`
      SELECT 
        kv.id,
        kv.user_id,
        kv.provider,
        kv.status,
        kv.risk_level,
        kv.created_at,
        kv.updated_at,
        ss.match_found as sanctions_match,
        kat.action,
        kat.actor_type,
        kat.timestamp as audit_timestamp
      FROM kyc_verifications kv
      LEFT JOIN sanctions_screening ss ON kv.id = ss.kyc_verification_id
      LEFT JOIN kyc_audit_trail kat ON kv.id = kat.kyc_verification_id
      WHERE kv.created_at >= $1 AND kv.created_at <= $2
      ORDER BY kv.created_at DESC
    `, [auditPeriod.start, auditPeriod.end]);

    return {
      period: auditPeriod,
      total_verifications: auditData.length,
      compliance_metrics: this.calculateComplianceMetrics(auditData),
      audit_trail: auditData,
      regulatory_exceptions: await this.identifyRegulatoryExceptions(auditData)
    };
  }
}