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.
Your product collects applicant data in its own experience. The backend then submits that package to Sumsub and reconciles the review result with Payblr.
Integration model
Your product collects applicant data in its own experience, then the backend submits that package to Sumsub and reconciles the review result with Payblr.
| Step | What the backend does |
|---|---|
Create the applicant | The client backend creates the Sumsub applicant with the Payblr identifiers and the level selected for the applicant's country of residence. |
Submit verification data | The backend uploads identity documents, submits the questionnaire, and adds TIN or proof of address only when the selected level requires them. |
Request review and reconcile the result | The backend requests review, then uses the Payblr-processed Sumsub result as the final KYC decision. |
Final decision rule: The final KYC decision must be based on the applicant review result processed by Payblr. Do not treat a successful API submission as approval.
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, selected by the client | Yes | One of three client-prefixed levels. Select <client>-kyc-individuals-address, <client>-kyc-individuals-address-tin, or <client>-kyc-individuals-poa-batch before applicant creation. |
partnerName | Payblr | Yes | Partner Id metadata used in Payblr reporting. Format is provided by Payblr during onboarding, commonly Processor-Partner, for example Processor-YourCompany. |
App Token and Secret Key | Sumsub / Payblr setup | Yes | 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. Payblr also assigns three levelName values. Replace <client> with the client name prefix. The levels are <client>-kyc-individuals-address, <client>-kyc-individuals-address-tin, and <client>-kyc-individuals-poa-batch. Select the level before creating the applicant. See Verification Journey for the selection rule.
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.