KYC via SumSub integration

A new integration with SumSub as a KYC service provider has been implemented through the NodeRed low-code solution. Basic external provider APIs for performing customer document verification checks were integrated. Additionally, internal SDK APIs were extended to update users’ identification statuses based on the verification results within the SDK system. 

The SDK system has implemented technical integration with SumSub’s User Verification API through the NodeRed solution, supporting basic features for user document verification and AML screening and monitoring. These features are embedded into the onboarding process within the SDK system.

The availability of features from the vendor (SumSub) to the client depends on the client’s needs and their agreements with the vendor. The SDK system provides a quick and easy way to integrate with SumSub, catering to both source code and cloud clients.

How to Start Using the Service

1. 1. Make an Agreement with the Provider:
      • The client must make an agreement with the KYC service provider (SumSub). All features available from the vendor to the client (for both source code and cloud clients) depend on the client’s needs and their agreements with the vendor.
   2. Get Credentials from the Provider:
      • After the agreement, the service provider will provide the client with credentials to access the Test and Production Environments.
      • Generate an API key in the provider’s environment and use it for SumSub integration setup.
   3. Set Up the Provider Connectivity Settings in the NodeRed Instance:
      • Configure the connectivity settings in the NodeRed instance.
      • Update the system configuration file with the necessary settings.
   4. Set Up Connectivity Between Kafka and NodeRed Instances:

• Configure the connectivity settings between Kafka and NodeRed instances.

1. • Provide NodeRed with access to certain Kafka topics with the required read/write permissions.
2. Activate SumSub KYC Service in the SDK Core App:
   • Activate the SumSub KYC service in the SDK Core App.
   • Update the system configuration file with the necessary settings.

How it works

User Document Verification

The user of the SDK platform provides user profile data and uploads documents via the front-end app (web or mobile). The Compliance Manager within the SDK system initiates document verification through a third-party KYC service provider. The SDK submits user data to Kafka topics based on specific conditions. The NodeRed system then reads these topics, processes the data, and passes it to SumSub via the provider’s REST APIs.

When the response from the provider is received, NodeRed calls the SDK APIs to update the status of the user’s document and identification according to the provider’s response. Additionally, NodeRed creates notes about the user, including the provider’s response details.

This solution allows us to extend the flow and modify the configuration for integration without making changes to the core SDK application’s code.

AML Screening and Monitoring

In this scenario, AML screening is performed via SumSub, which uses Comply Advantage as the source of data for watchlist screening. Comply Advantage provides real-time sanctions and watchlist screening using global lists and databases from governmental, law enforcement, and regulatory bodies.

Test Environment: Document-Based AML Check

In the test environment, we support a document-based AML check scenario. Here, the user’s name and date of birth are extracted from the identity document uploaded during the document verification flow. The results of the AML check are available in the Watchlists section of the applicant profile in the SumSub account, displaying all statuses, metrics, and details for interpretation and management.

SumSub offers a variety of configurable AML check options through their account. For more detailed information, visit the provider’s website.

SDK Capabilities:

• Compliance Manager Actions: On the SDK side, the Compliance Manager can manually change user statuses based on the AML check results.
• User Notifications: The SDK system can notify the user about changes in their status and the need to provide additional documents for AML checking.

This setup ensures thorough AML screening and monitoring, with flexibility for the Compliance Manager to manage and respond to screening results effectively.

Supported operations

The SumSub KYC integration service in the SDK platform supports basic methods of the User Verification API for user document verification and AML Screening and Monitoring. For more details, refer to the SumSub user verification API documentation here.

Flows Supported in the Test Environment

Document Verification

There are two modes for user document verification: Automated and Manual.

Automated

In this flow, documents are automatically sent for verification to the provider immediately after the user uploads them and confirms the upload during the KYC procedure. Following the provider’s response, the system will automatically update the user document status and user identification status based on the verification results.

User flow for ID document verification during onboarding:

1. The user uploads identification documents during the onboarding process in the SDK (user document status is IN_VERIFICATION, user identification status is PENDING, user contract type is BASE).
2. The system submits the user documents (one by one) to SumSub for verification.
3. The system receives verification results from SumSub (for each document separately):
   • GREEN: User document status transitions to APPROVED, user identification status transitions to APPROVED (if all required documents are approved), and user contract type transitions to STANDARD automatically.
   • RED (final): User document status transitions to DECLINED, user identification status remains PENDING, and user contract type remains BASE.
   • RED (retry): The system shows the Compliance Manager the issues with the user’s documents that can potentially be resolved. Compliance informs the user about the problem, for example: “The text on your identity document is not clearly visible. Upload a new photo” (communication with the user occurs outside the system OR via email notification generated by the system). The user re-uploads documents, and the system re-runs the check via SumSub (user document status is PENDING, user identification status is PENDING, user contract type remains BASE until updated by SumSub).

The user contract type determines the availability of certain operations in the system. Before verification, the user’s contract type is BASE, which limits their actions. After successful verification, the user’s contract type automatically changes to STANDARD, granting access to additional operations in the system.

Manual

The Compliance Manager submits user documents for verification to the SumSub KYC service provider on-demand as part of the KYC process. Following the provider’s response, the system will automatically update the user document status and user identification status based on the verification results.

AML Screening and Monitoring

Document-based AML verification occurs on the provider’s side after the user submits documents for verification. The name and date of birth are extracted from the identity document and matched against a comprehensive set of watchlists to find/exclude a match.

The Compliance Manager views the results of the AML check in the applicant’s profile on the SumSub account and manually changes the SDK user status accordingly (e.g., block or freeze the SDK user account if necessary).

Business process and APIs flow

Integration setup

• As a Platform Owner:

1. Sign an Agreement with SumSub:
   • Sign an agreement with the SumSub provider to obtain access credentials.
2. Register with SumSub:
   • Register with the SumSub system to generate your API key and manage check configurations.
3. Sign an Agreement for AML Screening:
   • Sign an agreement with the Watchlist source provider (Comply Advantage or World-Check One) to obtain access credentials.
   • Register with the Watchlist source provider system to generate your API key.
   • Configure AML checks in your SumSub account using the credentials obtained from the Watchlist source provider.

1. As an Administrator of the Platform:

1. SDK Core Configuration:
   • Verify the availability of the SumSub Integration Service in the SDK Core configuration file (application.yaml).
   • Ensure the following environment variable is set: enable: kyc_provider_available=true.
   • Set other environment variables according to the required business flow.
2. NodeRed Instance Setup:
   • Check the availability of the NodeRed instance.
   • Set up provider credentials in the NodeRed environment variables by setting the API key generated via the SumSub back-office.
3. Kafka Instance Availability:
   • Ensure the Kafka instance is available and properly configured.

III. As a Business User:

1. Register at the SDK System:
   • Register within the SDK system.
2. Provide User Profile Data:
   • Submit user profile data via UI or API. At a minimum, provide the user’s first and last name, year of birth, and country to perform KYC checks.
3. Upload Identification Documents:
   • Upload identification documents for verification via UI or API.
4. Confirm Document Upload:
   • Review and confirm the uploaded documents. Once confirmed, the user’s DocumentApprovalStatus is set to IN_VERIFICATION and OrganizationStatus to PENDING.

1. As a Compliance Manager (after the user uploads documents during the onboarding process):

1. Review User Documents:
   • The Compliance Manager reviews the user’s documents and decides whether to verify them via a third-party service provider (using UI or API).
2. Submit Document ID to Kafka:
   • The SDK system submits the Document ID to the Kafka topic user-profile-data if all required conditions are met (see required conditions below).
3. Process Document with NodeRed:
   • The NodeRed system reads the document IDs from user-profile-data and retrieves the document file from S3 storage.
   • The NodeRed system uploads the document files to the provider via API for verification.
4. Handle Provider Response:
   • Upon receiving a response from the provider, the NodeRed system submits the response details to separate topics (user-profile-data-response-sumsub and user-profile-data-response-sumsub-errors, depending on the results).
   • NodeRed calls the SDK API to update the user document and user identification statuses according to the results.
   • NodeRed creates notes related to the user, including the provider response details.

MANUAL FLOW required conditions to submit user documents for verification via 3rd third-party provider

• • API POST /profile-documents/{profileDocumentId}/users/{userId}/verify?providerKey=sumsub is received

• property sumsubIdVerification=true

• DocumentApprovalStatus=IN_VERIFICATION
• OrganizationStatus=Pending

if all conditions are satisfied the system submits the user document IDs to the topic user-profile-data.

NodeRed flows behavior depending on the provider verification results

1. If reviewAnswer = GREEN:
   • NodeRed calls POST /v1/profile-documents/{profileDocumentId}/approve to change DocumentApprovalStatus to APPROVED.
   • NodeRed calls POST /v1/users/note with response details.
   • NodeRed submits the provider response to the topic user-profile-data-response-sumsub.
2. If reviewAnswer = RED and rejectType = FINAL:
   • NodeRed calls POST /v1/profile-documents/{profileDocumentId}/decline to change DocumentApprovalStatus to DECLINED.
   • NodeRed calls POST /v1/users/note with response details.
   • NodeRed submits the provider response to the topic user-profile-data-response-sumsub.
3. If reviewAnswer = RED and rejectType = RETRY:
   • NodeRed calls PATCH /v1/profile-documents/{profileDocumentId}/users/{userId} to change DocumentApprovalStatus to REVIEW_REQUIRED.
   • NodeRed calls POST /v1/users/note with response details.
   • NodeRed submits the provider response to the topic user-profile-data-response-sumsub.
4. If an error occurs:
   • NodeRed calls POST /v1/users/note with response details.
   • NodeRed submits the response to the topic user-profile-data-response-sumsub-errors.
   • NodeRed retries sending API requests to the provider. In this error case, DocumentApprovalStatus remains PENDING and does not change.

 

The SDK System changes DocumentApprovalStatus and OrganizationStatus according to the API responses.

Initiate the automated document verification via the SumSub KYC service provider from the SDK platform.

For a business user, the flow of verification in automated mode does not change—the documents will be sent for verification to the provider in the same way, but without the Compliance Manager’s involvement.

After the user uploads and confirms documents (DocumentApprovalStatus=IN_VERIFICATION and OrganizationStatus=pending), they will be sent for verification to the Kafka topic user-profile-data automatically if all conditions are satisfied (see required conditions below).

AUTOMATED FLOW required conditions to submit user documents for verification via 3rd third-party provider

• property autoDocumentVerification=true

• property defaultDocumentVerificationProvider=sumsub

• property sumsubIdVerification=true

• DocumentApprovalStatus=IN_VERIFICATION
• OrganizationStatus=Pending

For the AUTOMATED FLOW, NodeRed behavior depending on the provider verification results is the same as for the manual process.

AML Checks via SumSub KYC Service Provider from the SDK Platform (using ComplyAdvantage as the watchlist source)

1. As a Business User:

• Register at the SDK System:

1. 1. • Register within the SDK system.

• Provide User Profile Data:

1. 1. • Submit user profile data via UI or API. At a minimum, provide the user’s first, last, and middle name, year of birth, country, and company name (for merchant users) to perform KYC checks.

• Upload Identification Documents:

1. 1. • Upload identification documents for verification via UI or API.

• Confirm Document Upload:

1. • Review and confirm the uploaded documents. Once confirmed, the user’s DocumentApprovalStatus is set to IN_VERIFICATION and OrganizationStatus to PENDING.

1. As a Compliance Manager (after the user uploads documents during the onboarding process):

• Review User Documents:

1. 1. • Review the user’s documents and decide to verify them via a third-party service provider manually, or the documents are sent for verification automatically if automated mode is on.

• Submit Document ID to Kafka:

• The SDK system submits the Document ID to the Kafka topic user-profile-data if all required conditions are met (see required conditions below). The NodeRed system passes documents to SumSub as described above.

• Perform AML Check:

1. 1. • If the AML check is configured on the SumSub account, the SumSub system performs the check according to the configuration. In the test environment, document-based AML verification is available. Document-based AML verification occurs on the provider side after the user submits the documents for verification. The name and date of birth extracted from the identity document are matched against a comprehensive set of watchlists to find/exclude a match.

• Review AML Check Results:

1. 1. • The Compliance Manager sees the results of the AML check in the applicant’s profile in the SumSub account and manually changes the SDK user profile status accordingly.

• To block: API PATCH /v1/users/{userId}, pass “paramType”: “ACTIVE”, “paramValue”: true.

• To freeze: API PATCH /v1/users/{userId}, pass “paramType”: “FROZEN”, “paramValue”: true.

• Update User Identification Status:

1. 1. • The Compliance Manager updates the user identification status in the SDK according to the AML verification result (if needed) and requests required documents for further AML verification.

• API PATCH /v1/profiles/{userId}?notify=true and provide “requiredDocuments” to send a notification to the user with a list of required documents.

1. • The Compliance Manager can change the user identification status only according to the user identification status transition rules.

III. As a Business User:

1. 1. Receive Notifications:

• Receive notifications about account profile status and identification status changes according to the Compliance Manager’s actions. Available actions will depend on the profile and identification statuses.

User notifications

User Account blocking

Subject: Notice of Account Termination Due to AML Compliance 

To: User contact email

Message:

Dear [Customer’s Name], 

Following a review, we regret to inform you that your account with [Application Name] has been terminated due to compliance 

with our Anti-Money Laundering (AML) policy. To facilitate the closure, please provide your bank details for the

transfer of any remaining balance under your name. This process may take up to 30 working days. For further assistance, 

contact our customer support team at [Customer Support Contact Email]. 

Sincerely, 

[Service User First and Last Name]

[Service User Role]

[Application Name] Compliance Team

User Identification status changed to Review required

Subject: Request for Additional Documentation for Account Review Under AML Compliance

To: User contact email

Message:

Dear [Customer’s Name], 

We are writing to inform you that your account with [Appliication Name] is currently under review due to matches found in our 

watchlists, as part of our Anti-Money Laundering (AML) compliance procedures. To facilitate this review, we kindly 

request additional documentation from you. Please upload the required documents through our secure portal at your earliest 

convenience to ensure timely completion of the review process. If you have any questions or concerns, please reach out 

to our customer support team at [Customer Support Contact Email]. 

Required Documents: 

[list of required document that Compliance manager provide during user identification status change]

Thank you for your cooperation and understanding. 

Sincerely, 

[Service User First and Last Name] 

[Service User Role] 

[Application Name] Team

You can change the notification template in the System configuration file (application.yaml). 

APIs endpoints

SDK.finance APIs

API	Description
POST /v1​/profile-documents​/view	View all profile documents
POST /v1​/profile-documents​/{profileDocumentId}​/approve	Approve the profile document
PATCH /v1​/profile-documents​/{profileDocumentId}​/users​/{userId}	Update status of user identification document
POST ​/v1​/profile-documents​/{profileDocumentId}​/users​/{userId}​/verify	Verify the user document via 3rd-party provider
POST /v1/profiles/{userId}/approve	Decline the profile document
PATCH /v1​/profiles​/{userId}	Update organization status (user identification status)
POST /v1/profiles/{userId}/approve	To approve user identification status
POST /v1​/users​/note	To create notes about user
GET ​/v1​/users​/note​/{userId}	To get notes about user

SumSub`s APIs 

API	Description
Create applicant action	Use this method to create an applicant action for a certain applicant with the required steps configured in the specified verification level.
Add ID document	Adds an identification document to the verification flow.
Get applicant review status	Returns applicant review status.
Request applicant check	Initiates a check of the applicant profile.
Generate access token	Creates an applicant action token.

SDK Back-office: Manual for Compliance Manager for on-demand KYC

Steps for Performing User Document Verification through SumSub on-demand:

1. Login:
   • Login to the system as a Compliance Manager.
2. Select User:
   • Navigate to the “Users” section and select a user from the list.
3. Access User Profile:
   • Choose the “Details” and then the “KYC” tab on the user profile.
4. Review Uploaded Documents:
   • View the list of uploaded documents.
   • Press “View details” to review each document.
5. Verify Documents via 3rd Party:
   • Press the “Verify document via 3rd party” option to submit the user profile data to the SumSub provider via the NodeRed layer.
   • Repeat this step for all required user documents one by one.
6. Monitor Status Changes:
   • When the provider’s response is received, the user document and identification statuses will be updated accordingly.
   • Check the user documents and identification statuses in the “KYC” tab of the User Profile details.
7. Review Provider Response Details:
   • Review the notes about the user to see the provider’s response details.
   • Navigate to “User profile” -> “Details” -> “KYC” -> “View all notes” -> “View”.

SDK Back-office: Manual to change user profile status

Compliance Manager Actions Based on AML Verification Results

Scenario: Receiving a RED Flag

1. Login:
   • Login to the system as a Compliance Manager.
2. Select User:
   • Navigate to the “Users” section and select the user from the list.
3. Block User:
   • Choose “Details” and press “Block user.”
   • Provide the “Reason” for the action as AML (required for further user notification).
   • Optionally provide a “Description.”
   • Press “Block user.”
4. Outcome:
   • The user profile will be blocked, and the user will receive a notification with an explanation and further instructions.

Scenario: Receiving a YELLOW Flag

1. Login:
   • Login to the system as a Compliance Manager.
2. Select User:
   • Navigate to the “Users” section and select the user from the list.
3. Freeze User:
   • Choose “Details” and press “Freeze user.”
   • Optionally provide a “Reason” for the action.
   • Optionally provide a “Description.”
   • Press “Freeze user.”
4. Outcome:
   • The user profile will be frozen.
5. Request Further Checks:
   • Open the “KYC” tab on the user profile.
   • Press “Review required.”
   • Specify which documents the user should provide for further checks.
   • Switch on the toggle “Notify client.”
   • Press “Update client status.”
6. Outcome:
   • The user will receive a notification with an explanation and further instructions.