Sumsub Know Your Customer (KYC) Integration Guide
1. Overview
This guide explains how clients using Payblr's instance of Sumsub for KYC should create, retrieve, interpret, and process applicant verification results as part of the cardholder onboarding process.
Sumsub verification results are used by Payblr to determine whether an applicant is approved, rejected, eligible for resubmission, or requires additional compliance review before continuing with card issuance and activation.
The integration can be implemented using one or both models below.
Integration models
Choose the model that matches how your product will collect and process applicant verification data. Both models can be used together when needed.
| Model | Description | When to use |
|---|---|---|
SDK-based verification | The client launches the Sumsub WebSDK or MobileSDK so the applicant completes KYC inside the client web or mobile experience. | Use when the client wants an embedded applicant-facing verification experience. |
API-based verification | Applicant creation, document upload, questionnaire submission, check initiation, and result reconciliation are handled through backend API calls. | Use when the client will manage the KYC flow through backend services. |
Final decision rule: In both models, the final KYC decision must be based on the applicant review result processed by Payblr. SDK frontend events can be used for user experience tracking, but they should not be treated as the final approval or rejection decision.
1.1 Key Identifiers
These identifiers are required to create, route, retrieve, and reconcile applicants across Payblr, Sumsub, and your system.
| Identifier | Assigned by | Required | Purpose |
|---|---|---|---|
sourceKey | Payblr | Yes | Payblr-assigned client/program identifier used to route the applicant to the correct Payblr configuration. |
externalUserId | Client | Yes | Stable applicant/user identifier from the client system. |
applicantId | Sumsub | Yes, after create | Unique applicant identifier returned by Sumsub and used for API retrieval, review history, audit, and troubleshooting. |
levelName | Payblr | Yes | Determines the verification flow assigned to the applicant. |
partnerName | Payblr | Yes | Partner Id metadata used in Payblr reporting. Format is provided by Payblr during onboarding, commonly Processor-Partner, for example Processor-YourCompany. |
SDK access token | Sumsub, requested server-side | SDK only | Temporary token used to initialize the Sumsub WebSDK or MobileSDK for a specific applicant. |
App Token and Secret Key | Sumsub / Payblr setup | API only | Credentials used by the backend to sign Sumsub API requests. Never expose these in frontend or mobile code. |
Implementation note: The applicant payload should include both Payblr identifiers where required by the integration contract: sourceKey for client/program routing and partnerName for Partner Id reporting. Do not invent these values. Payblr provides them during onboarding.
1.2 Supported Applicant Outcomes
Payblr uses Sumsub verification results to determine how each applicant should continue through cardholder onboarding.
| Outcome | Meaning | Payblr Handling |
|---|---|---|
| Approved | Applicant passed verification. | Applicant may continue in the Payblr onboarding flow, subject to Payblr rules. |
| Resubmission requested | Applicant failed a retryable check. | Applicant must correct or resubmit information before approval. |
| Final rejection | Applicant failed with a final rejection. | Applicant must not continue onboarding. |
| PEP match | Applicant may require enhanced review. | Route to compliance review before approval. |
| AML or sanctions hit | Applicant may require compliance review or rejection. | Do not continue onboarding until resolved. |
Continue onboarding
Approved applicants may continue, subject to Payblr rules.
Resubmit or review
Retryable failures and PEP matches need correction or compliance review.
Block progression
Final rejections and unresolved AML or sanctions hits must not continue.
Next steps
Continue to the Verification Journey page to review the end-to-end applicant flow from creation through final KYC decision handling.