Sumsub KYC & Identity Verification
Relevant source files
The following files were used as context for generating this wiki page:
- src/lib/sumsub/client.ts
- src/lib/sumsub/enforcement.ts
- src/app/api/webhooks/sumsub/route.ts
- src/lib/db/queries/sumsub.ts
- src/lib/db/migrations/2026_07_19_001_sumsub.sql
- src/app/[locale]/(platform)/_providers/TradingOnboardingProvider.tsx/_providers/TradingOnboardingProvider.tsx)
- src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx
Sumsub KYC & Identity Verification is a core security and compliance module integrated into the platform to handle Know Your Customer (KYC) requirements. It manages the full lifecycle of identity verification, from frontend user onboarding and SDK initialization to backend status synchronization via secure webhooks and API polling.
The system is designed with multiple enforcement modes, allowing administrators to choose between making verification optional ("Observe only") or strictly mandatory for trading activities. It utilizes a dedicated database schema to track applicant progress and enforces rate limits on sensitive operations like access token generation.
Sources: src/lib/sumsub/enforcement.ts, src/app/[locale]/(platform)/_providers/TradingOnboardingProvider.tsx
System Architecture
The Sumsub integration consists of a client-side SDK for user interaction and a server-side client for administrative and synchronization tasks.
Core Components
- SumsubClient: A server-side class responsible for signing requests and communicating with the Sumsub API. It handles authentication using HMAC-SHA256 signatures.
- SumsubRepository: A database abstraction layer using Drizzle ORM to manage
sumsub_applicants,sumsub_webhook_events, and rate limit state. - Webhook Handler: A secure endpoint that processes asynchronous updates from Sumsub, verifying payloads using a shared secret.
- Onboarding Provider: A React context provider that orchestrates the KYC flow within the user interface, managing modal visibility based on current verification status.
Sources: src/lib/sumsub/client.ts:60-128, src/lib/db/queries/sumsub.ts, src/app/api/webhooks/sumsub/route.ts, src/app/[locale]/(platform)/_providers/TradingOnboardingProvider.tsx
Data Flow: Verification Lifecycle
The following sequence diagram illustrates how a user initiates verification and how the status is updated via webhooks.
The diagram shows the interaction between the user's browser, the platform backend, and the Sumsub external service during a typical verification session.
Sources: src/app/api/webhooks/sumsub/route.ts, src/app/[locale]/(platform)/_providers/TradingOnboardingProvider.tsx:420-460
Database Schema
The integration uses three primary tables to ensure data integrity and prevent replay attacks or excessive API usage.
| Table Name | Description |
|---|---|
sumsub_applicants | Stores the relationship between internal user_id and Sumsub applicant_id. Tracks current status and review results. |
sumsub_webhook_events | Logs processed webhooks using a unique fingerprint to prevent duplicate processing. |
sumsub_access_token_rate_limits | Tracks request counts per user to prevent abuse of the token generation endpoint. |
Sources: src/lib/db/migrations/2026_07_19_001_sumsub.sql
Applicant Statuses
The platform normalizes Sumsub's internal review answers into a simplified set of statuses used for enforcement logic.
| Platform Status | Sumsub Mapping Logic |
|---|---|
approved | reviewAnswer === 'GREEN' |
rejected | reviewAnswer === 'RED' |
on_hold | reviewStatus includes 'hold' |
pending | reviewStatus is present but not finalized |
not_started | No review data available |
Sources: src/lib/sumsub/client.ts:32-48
Enforcement Logic
Access to trading is governed by the requireSumsubTradingApproval function, which evaluates the integration's configuration and the user's status.
The flowchart demonstrates that "Required" enforcement specifically checks for an "approved" status on the exact level name configured in settings.
Sources: src/lib/sumsub/enforcement.ts:9-25
Administrative Configuration
Administrators configure the integration through the Integrations form. Key settings include:
- App Token & Secret Key: Used to sign server-to-server requests.
- Webhook Secret: Used to validate the
x-payload-digestheader on incoming webhooks. - Level Name: The specific Sumsub verification level (e.g., "basic-kyc") users must complete.
- Enforcement Mode:
Disabled: Integration is inactive.Observe only: Verification is prompted but optional; users can trade without it.Required: Users are blocked from trading until verified.
Sources: src/app/[locale]/admin/integrations/_components/AdminIntegrationsForm.tsx:280-335
Implementation Details
Request Signing
All requests to Sumsub must be signed using an HMAC-SHA256 hash of the timestamp, HTTP method, path, and request body.
// src/lib/sumsub/client.ts
buildSignature(timestamp: number, method: string, pathWithQuery: string, body = '') {
return createHmac('sha256', this.credentials.secretKey)
.update(`${timestamp}${method.toUpperCase()}${pathWithQuery}${body}`)
.digest('hex')
}
Sources: src/lib/sumsub/client.ts:63-67
Webhook Validation
Incoming webhooks are validated by calculating the HMAC digest of the raw request body and comparing it to the x-payload-digest header using timingSafeEqual to prevent timing attacks.
Sources: src/app/api/webhooks/sumsub/route.ts:55-75
Conclusion
The Sumsub KYC & Identity Verification system provides a robust framework for managing user compliance. By combining real-time SDK interactions with secure backend synchronization and flexible enforcement modes, the platform ensures that regulatory requirements can be met without compromising user experience or system security.
Sources: src/app/[locale]/(platform)/_providers/TradingOnboardingProvider.tsx, src/lib/sumsub/enforcement.ts