KYC Management

Purpose: Handle Know Your Customer (KYC) verification, document processing, and lead tracking for regulatory compliance.

KYC Management allows you to verify customer identities through document collection, identity verification flows, and compliance tracking. This is essential for regulatory requirements and risk management.

KYC Lead Management

Creating KYC Leads

KYC leads represent potential customers who need identity verification. You can create leads through:

Direct API creation - Programmatically create leads for customers
KYC Links - Self-service verification flows for customers
Import processes - Bulk upload from existing systems

curl https://wallet.swipelux.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_API_KEY' \
  --data '{
    "email": "customer@example.com",
    "fullName": "John Doe",
    "requiresKyc": true,
    "kycLevel": "individual"
  }'

Lead Status Management

Track KYC leads through their verification lifecycle:

Status	Description	Next Actions
`not_started`	Lead created, verification not begun	Send verification instructions
`in_progress`	Customer actively providing documents	Monitor progress, provide support
`under_review`	Manual review required	Compliance team review
`approved`	Verification completed successfully	Enable full account features
`rejected`	Verification failed or incomplete	Review rejection reasons

Document Management

Required Documents

Individual Verification:

Government-issued photo ID (passport, driver's license)
Proof of address (utility bill, bank statement)
Selfie for liveness verification

Business Verification:

Certificate of incorporation
Business registration documents
Director/shareholder identification
Proof of business address

Document Processing

# Check document status
curl https://wallet.swipelux.com/v1/customers/{customer_id}/kyc \
  --request GET \
  --header 'X-API-Key: YOUR_SECRET_API_KEY'

Response includes:

Document upload status
Verification results
Compliance flags
Review notes

Compliance Tracking

KYC Levels

Configure verification requirements based on risk levels:

Basic KYC - Email + basic information
Enhanced KYC - Full document verification
Premium KYC - Additional due diligence checks

Risk Scoring

Automatic risk assessment based on:

Geographic location
Document authenticity
Behavioral patterns
External data sources

Audit Trail

Complete audit logs for compliance reporting:

Document submission timestamps
Review decisions and reasoning
Status change history
Manual review notes

Lead Tracking and Analytics

Dashboard Metrics

Monitor KYC performance with key metrics:

Conversion rates - Leads completing verification
Processing times - Average verification duration
Approval rates - Successful vs rejected applications
Drop-off points - Where customers abandon the flow

Lead Pipeline Management

Active Leads:

New submissions requiring review
Documents pending validation
Manual review queue

Historical Analysis:

Completed verifications by time period
Rejection reason trends
Geographic distribution
Processing efficiency metrics

Webhooks and Notifications

KYC Status Updates

Subscribe to real-time status changes:

{
  "event": "kyc.status_updated",
  "data": {
    "customerId": "cus_123",
    "previousStatus": "under_review", 
    "newStatus": "approved",
    "timestamp": "2025-01-01T12:00:00Z",
    "reviewNotes": "All documents verified successfully"
  }
}

Notification Setup

Configure webhook endpoints for:

Status changes (kyc.status_updated)
Document uploads (kyc.document_received)
Review completions (kyc.review_completed)
Compliance alerts (kyc.compliance_alert)

👉 Configure Webhooks

Best Practices

Lead Management

Automated follow-ups for incomplete applications
Clear communication about requirements and status
Multiple verification methods to reduce abandonment
Mobile-optimized document capture flows

Compliance

Regular audits of verification processes
Documentation retention per regulatory requirements
Staff training on compliance procedures
Risk assessment updates based on regulatory changes

Performance Optimization

Streamlined workflows to reduce processing time
Automated decisions for low-risk applications
Quality assurance for manual reviews
Customer support for verification assistance

SumSub ShareToken Integration

Crypto Rails Workflow

For crypto rails operations requiring KYC verification, you can streamline the customer onboarding process using SumSub shareTokens. This approach eliminates redundant verification steps and improves conversion rates.

Workflow Overview

Create Customer: First create a customer with minimal data
Generate SumSub Token: Generate a shareToken from your SumSub integration
PATCH Customer: Update the customer with the shareToken
Token Refresh: Due to short TTL, repeat PATCH requests with new tokens as needed

# Create customer with minimal data
curl https://wallet.swipelux.com/v1/customers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_API_KEY' \
  --data '{
    "email": "customer@example.com"
  }'

Why PATCH for ShareTokens?

Short TTL: SumSub tokens expire quickly, requiring frequent updates
Crypto Rails Requirement: KYC verification is mandatory for crypto transfers
Seamless Updates: PATCH allows updating just the shareToken without affecting other customer data
Improved UX: Customers complete KYC once in SumSub, then use shareTokens for multiple applications

Integration Benefits

Faster Onboarding: Skip redundant identity verification steps
Higher Conversion: Reduced friction leads to better completion rates
Compliance Ready: Immediate KYC status for crypto rails operations
Token Management: Handle token expiration gracefully with PATCH updates

Integration Examples

React Integration

// Check KYC status
const checkKycStatus = async (customerId: string) => {
  const response = await fetch(`/api/customers/${customerId}/kyc`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  const kycData = await response.json();
  return kycData.status;
};
 
// Handle status updates
const handleKycUpdate = (status: string) => {
  switch (status) {
    case 'approved':
      // Enable full features
      enableAllFeatures();
      break;
    case 'rejected': 
      // Show resubmission flow
      showResubmissionOptions();
      break;
    case 'under_review':
      // Display waiting message
      showReviewStatus();
      break;
  }
};

Python Integration

import requests
 
def manage_kyc_leads():
    # Get pending leads
    response = requests.get(
        'https://wallet.swipelux.com/v1/kyc/leads',
        headers={'X-API-Key': 'your_api_key'},
        params={'status': 'under_review'}
    )
    
    leads = response.json()['data']
    
    for lead in leads:
        # Process each lead
        process_kyc_lead(lead)
 
def process_kyc_lead(lead):
    # Custom business logic for lead processing
    if lead['risk_score'] < 50:
        # Auto-approve low risk
        approve_kyc(lead['customer_id'])
    else:
        # Flag for manual review
        flag_for_review(lead['customer_id'])

Next Steps

Customer Creation - Create verified customers
KYC Links - Hosted verification flows
Transfers - Enable transfers for verified customers
Webhooks - Real-time status notifications

KYC Management

On this page