@venturialstd/kyc

KYC (Know Your Customer) Management Module for Venturial

Overview

This module provides comprehensive KYC (Know Your Customer) functionality for managing user verification, document uploads, and compliance tracking in fintech applications.

Features

• KYC Profile Management: Track user verification status and personal information
• Document Management: Upload and verify identity documents
• Verification Tracking: Monitor individual verification steps and checks
• Multiple Verification Levels: Support for basic, intermediate, advanced, and full verification
• Status Management: Track KYC status from pending to approved/rejected
• Provider Integration: Support for external KYC providers (AIPRISE, JUMIO, ONFIDO, etc.)

Installation

npm install @venturialstd/kyc

Usage

Module Setup

import { KYCModule } from '@venturialstd/kyc';

@Module({
  imports: [KYCModule.forRoot()],
})
export class AppModule {}

Basic Usage

import { KYCService, KYC_STATUS } from '@venturialstd/kyc';

@Injectable()
export class MyService {
  constructor(private readonly kycService: KYCService) {}

  async checkUserKYC(userId: string) {
    const isCompleted = await this.kycService.isKYCCompleted(userId);
    return isCompleted;
  }

  async updateKYCStatus(profileId: string, status: KYC_STATUS) {
    return this.kycService.updateStatus(profileId, status);
  }
}

Entities

KYCProfile

Main entity that tracks KYC verification for a user.

Key Fields:

• userId: Reference to the user
• status: Current KYC status (PENDING, APPROVED, REJECTED, etc.)
• verificationLevel: Level of verification (NONE, BASIC, INTERMEDIATE, ADVANCED, FULL)
• Personal information (firstName, lastName, dateOfBirth, etc.)
• Address information (addressLine1, city, country, etc.)

KYCDocument

Stores uploaded documents for KYC verification.

Key Fields:

• kycProfileId: Reference to KYC profile
• documentType: Type of document (PASSPORT, DRIVER_LICENSE, etc.)
• side: Document side (FRONT, BACK, BOTH)
• status: Document verification status
• fileUrl: URL to stored document file

KYCVerification

Tracks individual verification steps/checks within the KYC process.

Key Fields:

• kycProfileId: Reference to KYC profile
• verificationType: Type of verification (IDENTITY, ADDRESS, DOCUMENT, etc.)
• status: Verification status
• provider: External KYC provider name
• confidenceScore: Confidence score (0-100)

Constants

KYC_STATUS

enum KYC_STATUS {
  PENDING = 'PENDING',
  IN_PROGRESS = 'IN_PROGRESS',
  SUBMITTED = 'SUBMITTED',
  UNDER_REVIEW = 'UNDER_REVIEW',
  APPROVED = 'APPROVED',
  REJECTED = 'REJECTED',
  EXPIRED = 'EXPIRED',
  REQUIRES_UPDATE = 'REQUIRES_UPDATE',
}

KYC_VERIFICATION_LEVEL

enum KYC_VERIFICATION_LEVEL {
  NONE = 'NONE',
  BASIC = 'BASIC',
  INTERMEDIATE = 'INTERMEDIATE',
  ADVANCED = 'ADVANCED',
  FULL = 'FULL',
}

KYC_DOCUMENT_TYPE

enum KYC_DOCUMENT_TYPE {
  PASSPORT = 'PASSPORT',
  DRIVER_LICENSE = 'DRIVER_LICENSE',
  NATIONAL_ID = 'NATIONAL_ID',
  // ... and more
}

Services

KYCService

Main service for managing KYC profiles.

Methods:

• findByUserId(userId: string): Get KYC profile by user ID
• createOrUpdateProfile(userId: string, data: Partial<KYCProfile>): Create or update profile
• updateStatus(profileId: string, status: KYC_STATUS, reviewedBy?: string): Update KYC status
• updateVerificationLevel(profileId: string, level: KYC_VERIFICATION_LEVEL): Update verification level
• isKYCCompleted(userId: string): Check if user has completed KYC
• getVerificationLevel(userId: string): Get user's verification level

KYCProviderService

Service for managing external KYC provider integrations.

Methods:

• registerProvider(provider: KYCProvider): Register a custom KYC provider
• getProvider(name: string): Get a registered provider
• createVerification(userId: string, providerName: string, userData): Create verification with provider
• syncVerificationResult(providerName: string, sessionId: string): Sync provider result to KYC entities
• handleProviderWebhook(providerName: string, payload: unknown): Handle webhook from provider

External Provider Integration

The module supports integration with external KYC providers (AIPRISE, JUMIO, ONFIDO, etc.) through a provider interface.

Using Default Providers

import { KYCModule, KYCProviderService } from '@venturialstd/kyc';

@Module({
  imports: [KYCModule.forRoot()], // AIPRISE provider registered by default
})
export class AppModule {}

Using Custom Providers

import { Injectable } from '@nestjs/common';
import {
  KYCModule,
  KYCProvider,
  ProviderDocumentData,
  ProviderUserData,
} from '@venturialstd/kyc';

@Injectable()
class MyCustomProvider implements KYCProvider {
  readonly name = 'MY_PROVIDER';
  
  async createVerificationSession(userId: string, userData: ProviderUserData) {
    // Your implementation
  }
  
  async getVerificationStatus(sessionId: string) {
    // Your implementation
  }
  
  async handleWebhook(payload: unknown) {
    // Your implementation
  }
  
  async uploadDocument(sessionId: string, documentData: ProviderDocumentData) {
    // Your implementation
  }
}

@Module({
  imports: [
    KYCModule.forRoot({
      providers: [MyCustomProvider], // Pass the class, not an instance
      registerDefaultProviders: false, // Disable default providers
    }),
  ],
})
export class AppModule {}

Creating Verification with Provider

import { Injectable } from '@nestjs/common';
import { KYCProviderService } from '@venturialstd/kyc';

@Injectable()
export class VerificationService {
  constructor(private readonly kycProviderService: KYCProviderService) {}

  async startKYCVerification(userId: string) {
    const session = await this.kycProviderService.createVerification(
      userId,
      'AIPRISE', // Provider name
      {
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]',
      },
    );

    // Redirect user to session.redirectUrl or embed session.widgetConfig
    return session;
  }

  async handleWebhook(providerName: string, payload: unknown) {
    return this.kycProviderService.handleProviderWebhook(providerName, payload);
  }
}

Webhook Endpoint Example

import { Controller, Post, Body, Param } from '@nestjs/common';
import { KYCProviderService } from '@venturialstd/kyc';

@Controller('webhooks/kyc')
export class KYCWebhookController {
  constructor(private readonly kycProviderService: KYCProviderService) {}

  @Post(':provider')
  async handleWebhook(
    @Param('provider') provider: string,
    @Body() payload: unknown,
  ) {
    return this.kycProviderService.handleProviderWebhook(provider, payload);
  }
}

DTOs

CreateKYCProfileDto

DTO for creating a new KYC profile.

UpdateKYCProfileDto

DTO for updating an existing KYC profile (extends PartialType of CreateKYCProfileDto).

License

MIT