Skip to content
Switch to light mode

Sumsub Know Your Customer (KYC) Integration Guide

3. SDK-Based Verification

In the SDK model, the client uses the Sumsub WebSDK or MobileSDK to present the applicant-facing verification experience.

The SDK is used for applicant data capture and verification. The final KYC decision must still be based on Payblr's processed Sumsub result.

On this page

3.1 SDK Flow Summary

  1. 1

    The applicant starts KYC in the client web or mobile application.

  2. 2

    The client application requests a KYC session from the client backend.

  3. 3

    The client backend generates the SDK access token in Sumsub using the applicant's externalUserId and the configured levelName.

  4. 4

    The client backend retrieves or confirms the applicant record using externalUserId.

  5. 5

    The client backend provides required custom fields via PATCH.

  6. 6

    The client backend returns the SDK access token to the client application.

  7. 7

    The client application launches the Sumsub WebSDK or MobileSDK.

  8. 8

    The applicant completes the required verification steps.

  9. 9

    Sumsub performs automatic checks and may request manual review.

  10. 10

    Sumsub sends the applicantReviewed result to Payblr.

  11. 11

    The client backend may retrieve applicant review status to view the latest status via API or webhook configuration.

  12. 12

    Payblr receives the result and returns the final handling result according to the reviewAnswer from the applicant status flow.

3.2 SDK Flow Diagram

The sequence below shows how the applicant, client application, client backend, Sumsub, and Payblr interact during SDK-based verification.

KYC SDK Integration

SDK-based verification sequence

User

Applicant

Client

Web / Mobile App

Client

Client Backend

Provider

Sumsub

Platform

Payblr

Starts KYC verification

ApplicantWeb / Mobile App

Request KYC session

Web / Mobile AppClient Backend

Generate SDK access token

SDK flow

Provide externalUserId and levelName

Client BackendSumsub

Return SDK access token / session details

SumsubClient Backend

Get applicant data with externalUserId

Client BackendSumsub

Provide applicantId

SumsubClient Backend

Provide custom fields via Change profile data details

Client BackendSumsub

Applicant updated

SumsubClient Backend

Provide SDK access token

Client BackendWeb / Mobile App

Launch WebSDK / MobileSDK

SDK flow
Web / Mobile AppSumsub

Complete verification steps

ApplicantSumsub

Perform automatic check / manual review

SumsubprocessesSumsub

Send applicantReviewed result

SDK flow
SumsubPayblr

Get applicant review status

applicantReviewed webhook or Get applicant data API

Client BackendSumsub
altGREEN

Verification completed

GREEN path

PayblrClient Backend
altRED

Verification rejected

RED path

PayblrClient Backend

Route to compliance review

Approve, reject, or request action

PayblrprocessesPayblr

Final handling result

SDK flow
PayblrClient Backend
sequenceLaneCenter(index, columnCount)
Applicant verification through WebSDK or MobileSDK, with final handling driven by Payblr-processed Sumsub results.

3.3 SDK Integration Requirements

Clients using the SDK must integrate with Payblr in a way that protects Sumsub credentials.

SDK Responsibilities

AreaClient ResponsibilityPayblr Responsibility
SDK launchLaunch Sumsub WebSDK or MobileSDK in the client application.Confirm the configured KYC flow.
Applicant identityProvide a stable externalUserId.Assign and validate the client/program configuration through sourceKey.
SDK tokenGenerate or request the SDK access token server-side.Provide required configuration details, such as assigned sourceKey and expected levelName.
Applicant dataRetrieve applicant data, provide custom fields, and keep applicant references.Process the applicant result received from Sumsub.
Result handlingDo not treat SDK frontend events as the final KYC decision.Process final KYC results through applicantReviewed and compliance handling.

SDK Implementation Notes

Use the following notes as final implementation reminders when integrating the Sumsub WebSDK or MobileSDK.

AreaWebSDKMobileSDK
KYC session requestThe client application requests a KYC session from the client backend.The mobile app requests a KYC session from the client backend.
Access token generationThe client backend generates the SDK access token.The backend generates the applicant SDK access token.
SDK launchThe frontend launches Sumsub WebSDK using the access token.The mobile app initializes the Sumsub MobileSDK using the access token.
Frontend or app eventsThe SDK may provide frontend events for user experience tracking.The client must support token refresh or token expiration handling where applicable.
Final decision sourceFinal onboarding decisions must be based on Payblr-processed KYC results, not only SDK frontend events.The final decision must be based on Payblr result processing.

SDK Access Token Handling

  • SDK access tokens must be generated server-side.
  • SDK access tokens must not be generated or signed in the frontend or mobile application.
  • The access token should be tied to the applicant and verification level.
  • The access token should only be used to initialize the applicant's SDK flow.
  • The client should treat the access token as temporary and support refreshing or requesting a new token when the token expires.

Never expose Sumsub App Token or Secret Key material in frontend or mobile code. Only temporary applicant SDK access tokens should reach the client application.

Next steps

Continue to API Integration if your backend will manage applicant creation, document upload, check initiation, and result reconciliation without the SDK UI.