​

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:

​

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