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