KYC Verification Flow

This guide details the complete verification process in the FinHub platform v2.1. The new APIs integrate verification directly into the customer registration flow, with automatic verification request creation and streamlined document upload. The process ensures compliance with regulatory requirements while providing a seamless user experience.

Flow Overview

The following sequence diagram illustrates the integrated verification process with v2.1 APIs:

Key Improvements in v2.1

Integrated Flow: Verification request created automatically during registration
Streamlined Upload: Single endpoint for all document types
Smart Processing: Risk-based routing for automated vs manual review
Real-time Status: Webhook notifications for status changes
Automatic Activation: Account activation immediately after approval

Prerequisites

Customer registered with verification request ID (from registration response)
Admin token for initial operations
Valid verification documents ready for upload

Detailed API Flow

Step 1: Upload Verification Documents

Upload all required verification documents based on the customer’s risk category. API Request:

POST /api/v2.1/verification/documents/upload
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Request Body:

{
  "verificationRequestId": "ver_req_xyz789",  // From registration response
  "documents": [
    {
      "type": "IDENTITY_DOCUMENT",
      "subType": "PASSPORT",
      "content": "base64_encoded_document_content",
      "fileName": "passport.jpg",
      "mimeType": "image/jpeg",
      "metadata": {
        "documentNumber": "AB1234567",
        "issuingCountry": "US",
        "expiryDate": "2030-01-01",
        "extractedData": {
          "firstName": "John",
          "lastName": "Doe",
          "dateOfBirth": "1985-05-15",
          "nationality": "US"
        }
      }
    },
    {
      "type": "PROOF_OF_ADDRESS",
      "subType": "UTILITY_BILL",
      "content": "base64_encoded_document_content",
      "fileName": "utility_bill.pdf",
      "mimeType": "application/pdf",
      "metadata": {
        "issueDate": "2025-01-01",
        "issuer": "NYC Power Company",
        "address": {
          "street": "123 Main Street",
          "city": "New York",
          "postalCode": "10001",
          "country": "US"
        }
      }
    }
  ]
}

Response:

{
  "data": {
    "verificationRequestId": "ver_req_xyz789",
    "documentsProcessed": 2,
    "status": "DOCUMENTS_RECEIVED",
    "processingDetails": {
      "identityDocument": {
        "status": "VALIDATED",
        "extractedData": {
          "documentNumber": "AB1234567",
          "fullName": "JOHN DOE",
          "dateOfBirth": "1985-05-15",
          "matchScore": 98
        }
      },
      "proofOfAddress": {
        "status": "VALIDATED",
        "addressVerified": true
      }
    },
    "nextStep": "AWAIT_VERIFICATION_RESULT",
    "estimatedProcessingTime": "2-5 minutes"
  }
}

Key Features:

OCR Data Extraction: Automatic extraction of document data
Data Validation: Cross-checks extracted data with registration data
Match Scoring: AI-based matching of document photos with selfies (if required)
Address Verification: Validates proof of address against registered address

Step 2: Check Verification Status

Monitor the verification status through polling or webhooks. API Request:

GET /api/v2.1/verification/status/{verificationRequestId}
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Response (Automated Approval):

{
  "data": {
    "verificationRequestId": "ver_req_xyz789",
    "customerId": "cust_abc123def456",
    "status": "APPROVED",
    "riskLevel": "MEDIUM",
    "verificationMethod": "AUTOMATED",
    "completedAt": "2025-01-23T10:05:00Z",
    "checks": {
      "identity": {
        "status": "PASSED",
        "confidence": 98.5
      },
      "address": {
        "status": "PASSED",
        "verified": true
      },
      "sanctions": {
        "status": "CLEAR",
        "listsChecked": ["OFAC", "EU", "UN", "INTERPOL"]
      },
      "pep": {
        "status": "NOT_PEP",
        "checked": true
      },
      "ageVerification": {
        "status": "PASSED",
        "age": 39
      }
    }
  }
}

Response (Manual Review Required):

{
  "data": {
    "verificationRequestId": "ver_req_xyz789",
    "customerId": "cust_abc123def456",
    "status": "PENDING_REVIEW",
    "riskLevel": "HIGH",
    "reasonForReview": "PEP_MATCH_POSSIBLE",
    "assignedTo": "COMPLIANCE_TEAM",
    "estimatedReviewTime": "24-48 hours"
  }
}

Step 3: Handle Manual Review (High Risk Cases)

For high-risk customers, tenant admins can review and approve through the admin API. API Request:

POST /api/v2.1/admin/verification/review
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Request Body:

{
  "verificationRequestId": "ver_req_xyz789",
  "decision": "APPROVE",
  "reviewerNotes": "Confirmed identity through additional checks. PEP status verified as family member only.",
  "additionalChecks": [
    {
      "type": "VIDEO_CALL",
      "result": "PASSED",
      "performedAt": "2025-01-23T14:30:00Z"
    }
  ],
  "riskMitigation": {
    "enhancedMonitoring": true,
    "transactionLimits": {
      "dailyLimit": "5000.00",
      "requiresApprovalAbove": "1000.00"
    }
  }
}

Step 4: Account Activation

Once verification is approved, activate the customer account. API Request:

POST /api/v2.1/customer/individual/activate
Content-Type: application/json
Authorization: Bearer {admin_token}
X-Tenant-ID: {tenant_id}

Request Body:

{
  "customerId": "cust_abc123def456",
  "activationOptions": {
    "generateIBAN": true,
    "createWallet": true,
    "walletCurrency": "EUR",
    "sendWelcomeEmail": true,
    "applyRiskMitigation": true  // Apply limits from verification
  }
}

Response:

{
  "data": {
    "customerId": "cust_abc123def456",
    "status": "ACTIVE",
    "verificationStatus": "VERIFIED",
    "riskLevel": "HIGH",
    "accountDetails": {
      "iban": "FR1420041010050500013M02606",
      "walletId": "wal_def789ghi012",
      "appliedLimits": {
        "dailyTransactionLimit": "5000.00",
        "requiresApprovalAbove": "1000.00",
        "source": "RISK_MITIGATION"
      }
    }
  }
}

Document Requirements by Risk Level

Low Risk Customers

Identity Document: Passport, National ID, or Driver’s License
Selfie: Optional liveness check

Medium Risk Customers

Identity Document: As above
Proof of Address: Utility bill, bank statement (< 3 months old)
Selfie: Required with liveness detection

High Risk Customers

All Medium Risk requirements plus:
Source of Funds: Bank statements, employment contract
Enhanced Due Diligence: Video call verification may be required
Additional Documentation: Based on risk factors

Verification Checks

The v2.1 API performs comprehensive automated checks:

Identity Verification

Document Authenticity: AI-powered forgery detection
Data Extraction: OCR with 99%+ accuracy
Face Matching: Biometric comparison with selfie
Data Consistency: Cross-validation with registration data

Compliance Screening

Sanctions Lists: OFAC, EU, UN, INTERPOL, and 200+ lists
PEP Screening: Politically exposed persons database
Adverse Media: Negative news screening
Risk Scoring: ML-based risk assessment

Address Verification

Document Validation: Proof of address authenticity
Address Matching: Comparison with registered address
Geocoding: Location verification

Error Handling

Error Code	HTTP Status	Description
INVALID_DOCUMENT_FORMAT	400	Unsupported file format (use JPEG, PNG, PDF)
DOCUMENT_TOO_LARGE	413	File size > 10MB
POOR_IMAGE_QUALITY	422	Document not readable (blur, glare, partial)
EXPIRED_DOCUMENT	422	Identity document has expired
DATA_MISMATCH	422	Document data doesn’t match registration
DUPLICATE_UPLOAD	409	Document already uploaded
VERIFICATION_LOCKED	423	Too many failed attempts
UNSUPPORTED_DOCUMENT	422	Document type not accepted

Best Practices

Document Upload

Image Quality: Minimum 300 DPI, clear and unobstructed
File Format: JPEG or PNG for images, PDF for documents
File Size: Keep under 5MB for optimal processing
Document Preparation: Ensure all corners visible, no glare

Integration Tips

Progress Indicators: Show upload and processing status
Retry Logic: Allow re-upload for rejected documents
Webhook Integration: Use webhooks for real-time updates
Error Messages: Provide clear guidance for document issues

Security Considerations

Secure Upload: Use HTTPS for all document transfers
Data Encryption: Documents encrypted at rest
Access Control: Limit document access to authorized personnel
Retention Policy: Documents deleted per compliance requirements

Webhook Events

Subscribe to verification webhooks for real-time updates:

{
  "event": "verification.status.changed",
  "data": {
    "verificationRequestId": "ver_req_xyz789",
    "customerId": "cust_abc123def456",
    "previousStatus": "PENDING",
    "currentStatus": "APPROVED",
    "timestamp": "2025-01-23T10:05:00Z"
  }
}

Next Steps

After successful verification:

About FinHub

​KYC Verification Flow

​Flow Overview

​Key Improvements in v2.1

​Prerequisites

​Detailed API Flow

​Step 1: Upload Verification Documents

​Step 2: Check Verification Status

​Step 3: Handle Manual Review (High Risk Cases)

​Step 4: Account Activation

​Document Requirements by Risk Level

​Low Risk Customers

​Medium Risk Customers

​High Risk Customers

​Verification Checks

​Identity Verification

​Compliance Screening

​Address Verification

​Error Handling

​Best Practices

​Document Upload

​Integration Tips

​Security Considerations

​Webhook Events

​Next Steps

​Related API Documentation

KYC Verification Flow

Flow Overview

Key Improvements in v2.1

Prerequisites

Detailed API Flow

Step 1: Upload Verification Documents

Step 2: Check Verification Status

Step 3: Handle Manual Review (High Risk Cases)

Step 4: Account Activation

Document Requirements by Risk Level

Low Risk Customers

Medium Risk Customers

High Risk Customers

Verification Checks

Identity Verification

Compliance Screening

Address Verification

Error Handling

Best Practices

Document Upload

Integration Tips

Security Considerations

Webhook Events

Next Steps

Related API Documentation