# WebSDK

# Introduction

The easiest way to start with our solution is to use our WebSDK. We put lots of efforts to improve conversion of your users and we thought about little details that make a difference. You will love WebSDK because:

  • It is highly customizable (choose any steps you want, change styles or copy)
  • Feature a face liveness module that improves conversion and minimizes fraud
  • Adaptive design and mobile friendly
  • Gives hints to users about how to better pass the flow
  • Ability to continue on mobile
  • Automatically refreshes when status is changed

WebSDK Screen

# Integration overview

Integrating WebSDK is super easy. Here is an overview of what you should do:

  • [Backend] Create an Applicant request that describes what documents your user needs to submit
  • [Backend] Generate an Access token to pass it later on to WebSDK init function
  • [Frontend] Include our JS script and call an init function.

Play around with WebSDK demo to get a feel of what it looks like.

# Initialization

  • Test environment (used for integration and testing): https://test-api.sumsub.com
  • Production environment: https://api.sumsub.com

In this guide we will not go into the details of all configuration options. See the full WebSDK demo, where you can play with different configuration options. The demo will show the full cycle of WebSDK integration, including preliminary applicant requests.

# Authentication for requests from your backend

Authentication methods to access our API with requests from your backend are described in this section.

# Generating access token

To initialize a WebSDK you must generate a temporary access token, which is also passed to the WebSDK initialization. This action must be performed on the server side. Please also pass a userId parameter, that is unique and meaningful. It can be an external user ID in your system, or an email address. Although they may be used for testing, please do not randomly generate these IDs.

Do not reuse access tokens. Create a new access token every time you show a WebSDK. Each token has a lifespan, which you set upon its creation. To avoid its expiration, just create a new one each time.

# Applicant request

Applicant request is done only once, but a new access token must be generated every time you show the WebSDK.

You should make this request from your backend to control which applicants, with which documents, you need. You should also provide your internal user ID (externalUserId) to guarantee that no more than one applicant will be created for your user.

This request does not create the applicant. The applicantRequests are needed to ensure that the information on the required documents will be checked on the backend and cannot be falsified on the front. For each externalUserId you should make an applicantRequest. If you make a second request for the same externalUserId, then you get 204.

POST /resources/accounts/-/applicantRequests

When making an applicant request, you don't have to send us prefilled applicant data or ask users to fill such info as names, dob, addresses, etc. You can ask users to just upload images and then get the recognized document data by this method. It's the best way to increase your conversion because rejects of mismatches in names and typos will be excluded.

Example request:

Name Type Value
X-App-Token String App Token that you generate in our dashboard
X-App-Access-Sig String Signature of the request in the hex format
X-App-Access-Ts String Number of seconds since Unix Epoch in UTC
Accept String application/json
Content-Type String application/json
Name Type Required Description
body Hash Yes JSON structure

Returns the resulting JSON structure.

# Frontend integration

Include in your webpage a JS script:

Create a container for the WebSDK on your page, e.g.:

Initialize a WebSDK:

The following parameters are passed upon initialization:

Name Description
clientId Provided to you by Sum&Substance team (e.g "CoolCoinLtd")
externalUserId The ID in your system with which you generated the access token
accessToken An access token generated on your backend
uiConf (optional) If you want to customize the look and feel of WebSDK

You can also find all the steps outlined in the WebSDK demo log. The WebSDK customization is pretty flexible, please, play around with the demo to get a sense of what’s possible.

# Standalone working example

Below is a fully working example. Just substitute $YOUR_CLIENT_ID, $ACCESS_TOKEN and $YOUR_USER_ID with the appropriate values (see steps above), save it to an HTML file and open it in your browser.

# WebSDK messages

messageType Payload Description
onReady {} WebSDK is ready to pass verification
onResize { "height": 828 } Size of webSDK's window
onInitialized {} Initialization of webSDK
onApplicantRequestAccepted { "applicantRequestId": "" } ID of applicantRequest
onApplicantCreated { "applicantId": "" } Applicant ID
onStepInitiated { "idDocSetType": "", "types": [], "subTypes": "", "fields": "", "imageIds": "" } Initialization of verification step
stepCompleted {"step":""} Step has been passed (user uploaded the document)
onApplicantSubmitted {} Documents was submitted for verification
onApplicantResubmitted {} Documents was re-submitted for verification
applicantStatus { "createDate": "", "reviewStatus": "" } The verification status
onError { "code": "", "error": "" } Error (please contact the Sum&Substance technical team)
onActionSubmitted {} Applicant action was submitted
actionStatus {createDate: "", reviewStatus: ""} The verification status of Applicant action
actionCompleted { "action": "", "applicantActionId": "" } Applicant action was approved

# Receiving verification results

Your backend receives results via a web-hook mechanism. You can get the results via email, Slack or Telegram. But for production use we recommend setting up a web-hook endpoint that we would call when necessary:

  • We need a webhook URL from you to send your results to. You can set up webhooks in developer's space at test and production environments.
  • We may send several types of webhooks, but the one that is of interest to you is the one described in the "Getting verification results" section. We encourage you to carefully get accustomed to this section, since there are quite a few options for what the results may look like.
  • If you want to manually check the applicant status you can always do it by this method. However, we don't recommend using polling as base method for getting verification results and rather strongly encourage the webhook mechanism. If for some reason you missed the webhooks, don't worry: we make a note of everything that was attempted to be sent, and can resend failed webhooks at any point in time. If webhook request fails we attempt to resend it four times: after 5 minutes, 1 hour, 5 and 18 hours until request succeeds. Check createdAt field of webhook payload to make sure that you're getting relevant applicant status.
  • Also you can monitor webhook statuses and resend them manually on the API Health page of dashboard on test and production.

Please note that we may send several final webhooks, so be prepared to change the user's status on your side too. A typical example is when a user got approved, but later on he was detected as a fraudster, and therefore we block him with a second "RED" webhook.

In a test environment, checks will not be started automatically and therefore the webhooks will not be sent automatically either. Either ask us to do so manually, or trigger a webhook yourself by calling an API endpoint described here. Once integration is done and you have moved to the production environment, the webhooks will be sent automatically once the verification procedure has been completed.

# Errors

Error code Status Description
204 No Content The applicantRequest already exists or you have sent the request without body text
400 Bad request The server cannot process the request (e.g. malformed request syntax, size too large or invalid request message framing)
401 Unauthorized Your authentication parameters are not set correctly
500 Internal Server Error We had a problem with our server. Try again later or provide us with the correlationId sent in the JSON response
503 Service Unavailable We're temporarily offline for maintenance. Please try again later.

If you have any issues, you can always contact the Sum&Substance team.

Error How to fix it?
Mismatch origin Incorrect clientId. You can find the current value here
Access error Incorrect accessToken. May be you generating an access token for another externalUserId.
Your session has expired Expired accessToken. Make sure that you generate a new access token every time you initialize the webSKD.

# Getting the production key

# How can we get the production key?

In order to ensure the best experience for you and your users, before giving you access to the production environment, we would like to test the flow and pass the verification as your end-user. To do so, we would kindly ask you to provide us with a link to your server.

Ensure that:

  • Integration on the test environment is completed, works and meets your requirements:
  • There are no dev console errors or warnings
  • You saved our applicantIds to your database and matched your users
  • You received and successfully processed test webhooks from our side
  • You know how to correlate results received in the webhook payload with your users

Please note that we may send several final webhooks, so be prepared to change the user's status on your side too. A typical example is when a user got approved, but later on he was detected as a fraudster, and therefore we block him with a second "RED" webhook.

# What information should be provided to obtain the production key?

Please provide us with:

  • An email where we can send the production credentials
  • A webhook URL for the production environment (you can set them up by yourself here)
  • A list of countries to be excluded (Example: USA, RUS, IRL)
  • The age threshold for your users

# Twilio integration

If you want to allow your users to send verification links via SMS to their mobile devices, you have to set it up at dashboard on production and test and make sure that target regions are enabled in your twilio account here.


# How can we get the applicantId?

  • When a user completes a first page an applicant is created. At this moment we send webhook to your endpoint with type applicantCreated. Its payload will contain the applicantId
  • GET /resources/applicants/-;externalUserId=${externalUserId}

This endpoint will return a single element list if such an applicant with a given ${externalUserId} exists and is unique. An empty list is returned if a user did not fill out the initial form. Read the id field from the returned entity to get the applicantId.

# How to enable liveness check?

To enable liveness check you should pass videoRequired:liveness setting at SELFIE step of Applicant request's requiredIdDocs.docSets.

Liveness enable example:

# Where can I find my clientId?

Client Id is your identifier to use while initializing WebSDK. You can find at dashboard: production and test at the Client Id field.

ClientId is case sensitive. Make sure that you provided correct clientId initializing WebSDK.

Last Updated: 5/11/2020, 8:38:39 AM