​
KYC Verification Flow

This guide details the complete Know Your Customer (KYC) verification process in the FinHub platform. KYC verification is a mandatory step for customers to access full financial services, ensuring compliance with regulatory requirements.

​
Flow Overview

The following sequence diagram illustrates the complete KYC verification process, including both automated and manual review paths:

​
Detailed API Flow

​
Step 1: Upload KYC Document

The first step is to upload the required KYC documents for verification. API Request: 
POST /api/v2/kyc/documents/upload
Content-Type: multipart/form-data
Authorization: Bearer {access_token}
Request Form Data: 
organization: cust_12345678
purpose: pep-sanction
documentType: identity_document
file: [Binary data of the document image]
metadata: {
  "documentType": "PASSPORT",
  "documentNumber": "AB1234567",
  "issuingCountry": "United States",
  "expiryDate": "2030-01-01",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1985-05-15"
}
Response: 
{
  "documentId": "doc_12345678",
  "status": "RECEIVED",
  "uploadedAt": "2025-06-01T09:30:00Z",
  "documentType": "identity_document"
}
Implementation Notes:
  • The system accepts various document types (passport, ID card, driver’s license)
  • Document images should be clear and legible
  • Multiple documents may be required (front/back of ID, proof of address)
  • The metadata provides context for document verification

​
Step 2: Get Current Documents

After uploading documents, the system allows checking the status of all uploaded documents. API Request: 
GET /api/v2/kyc/documents
Content-Type: application/json
Authorization: Bearer {access_token}
Response: 
{
  "documents": [
    {
      "documentId": "doc_12345678",
      "customerId": "cust_12345678",
      "documentType": "identity_document",
      "status": "RECEIVED",
      "uploadedAt": "2025-06-01T09:30:00Z"
    },
    {
      "documentId": "doc_87654321",
      "customerId": "cust_12345678",
      "documentType": "proof_of_address",
      "status": "RECEIVED",
      "uploadedAt": "2025-06-01T09:35:00Z"
    }
  ]
}
Implementation Notes:
  • Documents may have different statuses (RECEIVED, PROCESSING, VERIFIED, REJECTED)
  • If a document is rejected, the system provides a reason
  • The customer may need to re-upload documents if they are rejected

​
Step 3: Get SEPA ID for Verification

The system generates a SEPA ID that is used for the verification process. API Request: 
GET /api/v2/customer/sepa-id
Content-Type: application/json
Authorization: Bearer {access_token}
Response: 
{
  "sepaId": "SEPA123456789",
  "expiresAt": "2025-06-01T10:30:00Z"
}
Implementation Notes:
  • The SEPA ID is a unique identifier for the verification process
  • The ID has an expiration time
  • This ID is used to track the verification process

​
Step 4: Start Verification Process

Once all required documents are uploaded, the verification process can be initiated. API Request: 
POST /api/v2/kyc/verification/start
Content-Type: application/json
Authorization: Bearer {access_token}
Request Body: 
{
  "customerId": "cust_12345678",
  "kycConfirmationStatus": "WAITING_CONFIRMATION"
}
Response: 
{
  "verificationId": "ver_12345678",
  "status": "PENDING",
  "startedAt": "2025-06-01T09:40:00Z",
  "estimatedCompletionTime": "2025-06-01T10:40:00Z"
}
Implementation Notes:
  • The verification process runs in the background
  • Automated verification typically takes 5-30 minutes
  • Manual verification may take up to 24-48 hours
  • The customer is notified when verification is complete

​
Step 5: Check KYC Status

The customer can check the status of their KYC verification at any time. API Request: 
GET /api/v2/customer/details
Content-Type: application/json
Authorization: Bearer {access_token}
Response: 
{
  "customerId": "cust_12345678",
  "person": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "kycStatus": "VERIFIED", // or "PENDING", "REJECTED"
  "kycVerificationMethod": "AUTOMATED", // or "MANUAL"
  "kycVerifiedAt": "2025-06-01T10:15:00Z",
  "kycRejectionReason": null // present if rejected
}
Implementation Notes:
  • The KYC status is updated in real-time
  • If verification is rejected, a reason is provided
  • The customer may need to restart the verification process if rejected
  • Successful verification unlocks full account functionality

​
Manual Review Process

In approximately 10% of cases, documents are flagged for manual review by compliance officers in the Business Control Panel:
  1. Document Flagging: The system flags documents that require manual verification
  2. Compliance Officer Assignment: A compliance officer is assigned to review the documents
  3. Document Review: The officer reviews all submitted documents and customer information
  4. Verification Decision: The officer approves or rejects the verification
  5. Customer Notification: The customer is notified of the verification result

​
Error Handling

The KYC verification process includes comprehensive error handling for various scenarios:
Error ScenarioError CodeDescription
Invalid document formatINVALID_DOCUMENT_FORMATThe document format is not supported
Document too largeDOCUMENT_TOO_LARGEThe document file size exceeds the limit
Poor image qualityPOOR_IMAGE_QUALITYThe document image is not clear enough
Expired documentEXPIRED_DOCUMENTThe identity document has expired
Missing required documentMISSING_DOCUMENTA required document type is missing
Information mismatchINFORMATION_MISMATCHDocument information doesn’t match provided details

​
Compliance Considerations

The KYC verification process is designed to comply with various regulatory requirements:
  1. Anti-Money Laundering (AML): Verifies customer identity to prevent money laundering
  2. Counter-Terrorism Financing (CTF): Screens against global watchlists
  3. Know Your Customer (KYC): Validates customer identity and assesses risk
  4. GDPR Compliance: Ensures proper handling of personal data
  5. Record Keeping: Maintains verification records for regulatory purposes

​
Next Steps

After successful KYC verification, the customer can:
  1. Create financial accounts
  2. Set up payment methods
  3. Initiate transactions
  4. Access additional financial services