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.

Getting started

  • 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 tokens. Create a new 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:

REQUEST HEADERS
Name Type Value
Authorization String Bearer token
Accept String application/json
Content-Type String application/json
REQUEST ARGUMENTS
Name Type Required Description
body Hash Yes JSON structure
RESPONSE

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": "" } Step's initialization
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)

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.
  • 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.

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.

Customization

WebSDK is flexible from the point of view of customization, you can add or change almost any text, use css, so that the webSDK was in the style of your service design.

You can play with customization here.

init

Name Description
includedCountries List of included countries
excludedCountries List of excluded countries
Name Description
showWelcomeScreen Display an additional screen which contains button Upload documents

uiConf

Name Description
customCss Ability to use your CSS-file with customized settings
lang Language which shows webSDK (default: en)
documentExamples You can change the document examples

steps

Name Description
instructions Changes the text on the screen
title Changes the title on the screen
videoRequired Using camera for taking photo/video
custom fields Adding other fields if needed

You can play with customization here.

Initialize a WebSDK (no effort):

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?

To give you the production key we need to test the integration. We just want to make sure that everything goes right. Please provide us with a link to your server where we can try to pass verification.

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 key
  • A webhook URL for the production environment
  • A list of countries to be excluded (Example: USA, RUS, IRL)
  • From which domains you will load our WebSDK (we will whitelist them)

FAQ

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 uiConf while initializing WebSDK.

Liveness enable example:

Where can I find my clientId?

Client Id is your identifier to use while initializing WebSDK. You can find it here at the Client Id field.

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

Migration guide from old WebSDK

If you are a new client, please, ignore this section.

We tried to make the migration process as simple as possible, but there are some differences from the previous version.

We kindly ask that you generate a new access token every time you show webSDK to the end user.

Last Updated: 11/11/2019, 10:23:08 AM