Example: KYC Verification

The Quicksilver SDK provides a robust framework for managing Know Your Customer (KYC) and Anti-Money Laundering (AML) compliance directly within your application. This example demonstrates how to create accounts, submit KYC documents, process verification (including admin actions for approval or rejection), and manage account capabilities based on verification status.

The Account active model is central to this process, providing fluent methods to interact with the KYC workflow. Additionally, the KycResource (part of API Reference: Resources (Legacy/Advanced)) offers direct API access for more granular control.

Below is the full working example from examples/6-kyc-verification.ts:

Understanding KYC Verification

KYC (Know Your Customer) is a critical process in financial services to verify the identity of clients and assess their suitability for financial products and services. The Quicksilver SDK integrates KYC directly into the Account model, enabling robust identity and compliance management.

The workflow typically involves:

1. Account Creation: Initializing accounts, which are often unverified by default.
2. Document Submission: Users or agents submit required identification documents.
3. Verification Review: An administrative process to review submitted documents and make a verification decision.
4. Status-based Capabilities: Account capabilities (e.g., transacting, delegating) are dynamically adjusted based on their verification status.

1. Initial Setup and Account Creation

The process begins by initializing the QuicksilverClient and creating accounts. For this demo, we create an individual and a business account. By default, new accounts created via client.accounts.create() will have their verification.status set to unverified, unless they are created as a root account (without a parent_id), in which case they are verified by the system automatically.

You can inspect the initial verification status and capabilities using methods on the Account model, such as getVerificationStatus(), canTransact(), and canDelegate():

Initially, for unverified accounts, canTransact() and canDelegate() will return false.

2. Submitting KYC Documents

Users can submit their KYC documents using the submitKYC() method on their Account instance. This method takes document_type and document_number as parameters, and optionally document_file for actual file uploads (though commented out in the example, it indicates the capability).

After submission, the account's verification.status typically transitions to pending or in_review, awaiting administrative action.

3. Verification Process (Admin Actions)

The SDK provides verify() and rejectVerification() methods on the Account model, intended for use by authorized administrators. These methods update the account's verification status in the Quicksilver Engine.

To verify an account:

To reject an account (e.g., due to insufficient documentation or high risk):

These actions are crucial for maintaining compliance and security within the system.

4. Post-Verification Status and Capabilities

After an account has been verified, its capabilities are unlocked. You can refresh the Account object to get the latest status from the server:

Verified accounts can now perform actions like updating limits or delegating sub-agents:

The canTransact() and canDelegate() methods provide a simple way to check if an account is eligible for these operations, enforcing business rules based on verification status.

5. Verification Workflow Summary and Compliance

The Quicksilver SDK's KYC features are designed to facilitate a comprehensive compliance strategy. The example concludes with a summary demonstrating the different states and capabilities achieved through the verification workflow, highlighting key compliance features:

This ensures that all financial interactions within the Quicksilver Engine can adhere to necessary regulatory standards.

The KycResource class, available via client.kyc, provides lower-level access to initiate KYC sessions (if using an external provider) and process webhooks, allowing for flexible integration with third-party KYC solutions. However, for most SDK users, the Account model's methods (submitKYC, verify, rejectVerification, getVerificationStatus) offer a streamlined, object-oriented approach.

This comprehensive approach to KYC ensures that developers can build secure, compliant, and feature-rich financial applications using the Quicksilver SDK.