How to Use Sumsub KYC Verification Service: A Complete Step-by-Step Guide
https://paylentra.com/product/sumsub-kyc-verification-service/
Whatsapp:
Telegram:
Sumsub (Sum verification) is a leading identity verification platform that helps businesses automate Know Your Customer (KYC), Know Your Business (KYB), Anti-Money Laundering (AML) screening, and fraud prevention.
Whether you are launching a fintech app, crypto exchange, marketplace, or any platform requiring identity compliance, this guide provides a step-by-step walkthrough on how to set up, integrate, and manage Sumsub’s KYC verification service.
Prerequisites
Before starting the integration, ensure you have:
A Sumsub Account (sign up at sumsub.com).
Access to the Sumsub Dashboard (Developer Console).
Basic knowledge of API calls (REST APIs) and frontend integration (HTML/JS or mobile SDKs).
Step 1: Account Setup and Sandbox Environment
To ensure a smooth launch without affecting live users, begin in the Sandbox (Test) Mode:
Log in to your Sumsub Dashboard.
Toggle to Sandbox Mode: In the upper menu, switch the environment from Production to Sandbox.
Generate API Keys:
Go to Dev Space > App Tokens.
Click Create App Token.
Provide a token description (e.g., Development Backend Token).
Assign the required permissions (Secret Key generation enabled).
Save your App Token and Secret Key securely. You will need these to sign server-to-server API requests.
Step 2: Configure Verification Levels (Workflows)
Sumsub uses Applicant Levels to define what documents and checks are required for a user during the onboarding flow.
Navigate to Dev Space > Applicant Levels.
Click Create Level or edit a default level (e.g., basic-kyc-level).
Select the required verification steps:
Identity Document: Passport, ID Card, Driver's License.
Liveness / Biometrics: 3D Facial Recognition scan.
Proof of Address (PoA): Utility bill, bank statement.
Questionnaire / PEP & Sanctions: AML screening against global databases.
Customize country-specific rules or strictness settings as required by your jurisdiction.
Step 3: Architecture Overview & Integration Flow
The standard Sumsub KYC integration consists of three main parts:
[ Client App / Frontend ] <---> [ Your Backend Server ] <---> [ Sumsub API ]
Your Backend authenticates with Sumsub using your API Keys and generates an Access Token for the user.
Your Frontend initializes the Sumsub WebSDK / Mobile SDK using the generated Access Token.
The User completes the verification steps inside the SDK iframe or app view.
Sumsub processes the submitted documents and sends a Webhook notification back to your server with the result.
Step 4: Backend Implementation (Generating Access Tokens)
Sumsub access tokens are temporary (usually valid for 10–15 minutes) and scoped to an individual user (userId).
- Generating the HMAC Signature
All server-to-server requests to Sumsub require an X-App-Access-Sig header signed using HMAC-SHA256 with your Secret Key.
- Requesting the Access Token
Make a POST request from your backend to Sumsub's API:
Endpoint: POST https://api.sumsub.com/resources/accessTokens?userId={userId}&levelName={levelName}
Headers:
X-App-Token: Your App Token
X-App-Access-Sig: Calculated HMAC-SHA256 signature
X-App-Access-Ts: Current Unix timestamp (in seconds)
Example Response:
{
"token": "sbx:_act-482f3a9e-8b1a-4f51-b883-exampleToken",
"userId": "user_12345"
}
Step 5: Frontend Integration (WebSDK Example)
Sumsub provides pre-built Web and Mobile SDKs that handle camera permissions, UI/UX, document validation, and error messaging out of the box.
WebSDK HTML/JavaScript Integration
Include the Sumsub WebSDK script and initialize it on your web page:
<!DOCTYPE html>
<!-- Container where the verification widget will render -->
<br>
// Fetch access token from your backend server<br>
async function getAccessToken() {<br>
const response = await fetch('/api/get-sumsub-token');<br>
const data = await response.json();<br>
return data.token;<br>
}</p>
<div class="highlight"><pre class="highlight plaintext"><code>async function launchKYC() {
const accessToken = await getAccessToken();
// Launch the WebSDK
const snsWebSdkInstance = snsWebSdk.init(
accessToken,
// Function to refresh token if it expires during the session
() => getAccessToken()
)
.withConf({
lang: 'en',
email: 'user@example.com'
})
.on('onApplicantSubmitted', (payload) => {
console.log('Applicant submitted documents:', payload);
})
.on('onApplicantReviewed', (payload) => {
console.log('Applicant review status:', payload);
})
.on('onError', (error) => {
console.error('WebSDK error:', error);
})
.build();
// Render the widget in the container
snsWebSdkInstance.launch('#sumsub-websdk-container');
}
launchKYC();
</code></pre></div>
<p>
Step 6: Handling Webhooks
Never rely solely on client-side callbacks to update a user's verification status in your system. Webhooks are essential for secure server-side synchronization.
Navigate to Dev Space > Webhooks in the Sumsub Dashboard.
Click Add Webhook Target.
Set your server endpoint URL (e.g., https://your-domain.com/api/webhooks/sumsub).
Select the events you wish to receive:
applicantReviewed: Triggered when an applicant's check is finalized (GREEN for approved, RED for rejected).
applicantPending: Triggered when document submission is complete and review starts.
Store the Secret Key provided for verifying incoming webhook signatures.
Handling applicantReviewed Payload Example
{
"applicantId": "60a7bc3f2e1f...",
"externalUserId": "user_12345",
"reviewStatus": "completed",
"reviewResult": {
"reviewAnswer": "GREEN"
},
"type": "applicantReviewed"
}
GREEN: User passed verification. Mark as verified in your database.
RED: User failed verification. Check rejectLabels and clientComment for detailed rejection reasons (e.g., expired ID, blurred photo).
Step 7: Testing in Sandbox Mode
Sumsub provides test documents to simulate various verification outcomes without using real IDs:
Download sample test documents from Sumsub’s official documentation (e.g., test passports, driver’s licenses).
Complete the WebSDK workflow using these test documents.
Observe how your backend handles webhook events for both approved and rejected outcomes.
Step 8: Moving to Production
When your integration tests pass and you are ready to go live:
Switch your environment toggle in the Sumsub Dashboard from Sandbox to Production.
Create production App Tokens and Secret Keys.
Update your backend environment variables to point to the production keys and live API base URL (https://api.sumsub.com).
Ensure your webhook endpoint points to your live server with SSL enabled (https://).
Summary of Best Practices
Always verify webhook signatures on your backend to prevent unauthorized request spoofing.
Implement token refresh handlers in the Web/Mobile SDK so users aren't disconnected if their session takes longer than expected.
Use Applicant Levels wisely: Match verification requirements to user risk profiles (e.g., light KYC for registration, full KYC for withdrawals).
Monitor Analytics: Utilize Sumsub's Dashboard metrics to monitor pass rates, average processing times, and drop-off points.
Top comments (0)