# 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

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

# Applicant request

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.

POST /resources/accounts/-/applicantRequests

Example request:

curl -X POST \
  'https://test-api.sumsub.com/resources/accounts/-/applicantRequests' \
  -H 'X-App-Token: `TOKEN`' \
  -H 'X-App-Access-Sig: 199b83aaf4380e1763e4a5fb53c16bd580edf23e7686706726bf7bf742bfadce' \
  -H 'X-App-Access-Ts: 1585683256' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
	"applicant": {
		"email": "",
		"requiredIdDocs": {
			"docSets": [{
				"idDocSetType": "IDENTITY",
				"types": ["ID_CARD", "PASSPORT", "DRIVERS", "RESIDENCE_PERMIT"]
			}, {
				"idDocSetType": "SELFIE",
				"types": ["SELFIE"]
			}]
		},
        // An applicant ID on the client side should be unique
		"externalUserId": "684f2102-aaeb-450e-8e4f-97898f7d7025"
	}
}'

fetch('https://test-api.sumsub.com/resources/accounts/-/applicantRequests', {
  method: 'POST',
  headers: {
    'X-App-Token: `TOKEN`',
    'X-App-Access-Sig: 199b83aaf4380e1763e4a5fb53c16bd580edf23e7686706726bf7bf742bfadce',
    'X-App-Access-Ts: 1585683256',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "applicant": {
      "email": "",
      "requiredIdDocs": {
        "docSets": [{
          "idDocSetType": "IDENTITY",
          "types": ["ID_CARD", "PASSPORT", "DRIVERS", "RESIDENCE_PERMIT"]
        }, {
          "idDocSetType": "SELFIE",
          "types": ["SELFIE"]
        }]
      },
      // An applicant ID on the client side should be unique
      "externalUserId": "684f2102-aaeb-450e-8e4f-97898f7d7025"
    }
  })
});

# REQUEST HEADERS

# REQUEST ARGUMENTS

# RESPONSE

Returns the resulting JSON structure.

# Frontend integration

Include in your webpage a JS script:

<script src="{$baseUrl}/idensic/static/sumsub-kyc.js"></script>
e.g.
<!-- don't forget to change this URL when switching to the prod environment -->
<script src="https://test-api.sumsub.com/idensic/static/sumsub-kyc.js"></script>

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

<!-- iframe will be inserted as a child element -->
<div id="idensic"></div>

Initialize a WebSDK:

<!-- See our demo to see which parameters are -->
<!-- passed to the iframe when selecting different options -->
<script>
  // ...
  var id = idensic.init(
    // selector of the WebSDK container (see above)
    '#idensic',
    // configuration object (see settings in the demo)
    {
      // provide your clientId (can be seen in the demo)
      clientId: 'yourClientId',
      // access token for specific externalUserId
      accessToken: 'accessToken',
      // may be some additional parameters, see the Demo to see which ones, e.g.
      externalUserId: 'someUserIdInYourSystem'
    },
    // function for the WebSDK callbacks
    function(messageType, payload) {
      // e.g. just logging the incoming messages
      console.log('[IDENSIC DEMO] Idensic message:', messageType, payload)
    }
  )
  // ...
</script>

import React from 'react'

class IdensicComp extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      idensicPath: props.baseUrl + '/idensic/static/sumsub-kyc.js'
    }
  }

  attachKycJs(idensicPath) {
    if (window.idensic) {
      return Promise.resolve()
    }

    return new Promise((resolve, reject) => {
      const script = document.createElement('script')
      script.onload = loadEvent => {
        if (window.idensic) {
          resolve()
        } else {
          reject(new Error('Idensic loaded but not executed'))
        }
      }
      script.onerror = errorEvent => {
        reject(new Error('Idensic not loaded'))
      }
      script.src = idensicPath
      document.head.appendChild(script)
    })
  }

  initIdensic() {
    // Set current values
    let config = {
      clientId: "{CLIENT_ID}",
      externalUserId: "{USER_ID}",
      accessToken: "{ACCESS_TOKEN}",
    }

    window.idensic.init(
      '#idensic-block',
      config,
      (messageType, payload) => {
        console.log('[IDENSIC]', messageType, payload);
      }
    )
  }

  componentDidMount() {
    this.attachKycJs(this.state.idensicPath)
      .then(() => {
        this.initIdensic()
      })
      .catch(error => console.error(error))
  }

  render() {
    return (
      <div>
        <div id="idensic-block"></div>
      </div>
    );
  }
}

function App() {
  return (
    <div className="App">
      <IdensicComp baseUrl="https://test-api.sumsub.com" />
    </div>
  );
}

export default App

The following parameters are passed upon initialization:

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.

<html>
	<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- replace with https://api.sumsub.com/idensic/static/sumsub-kyc.js when going live -->
    <script src="https://test-api.sumsub.com/idensic/static/sumsub-kyc.js"></script>
    <title>SumSub WebSDK integration example</title>
  </head>
	<body>
    <div id="idensic"></div>
	</body>
</html>
<script>
  var id = idensic.init(
    // selector of the WebSDK container (see above)
    '#idensic',
    // configuration object (see the settings in the demo)
    {
      // provide your clientId (shown in the demo in the top left corner)
      clientId: '$YOUR_CLIENT_ID',
      // access token generated for $YOUR_USER_ID
      accessToken: '$ACCESS_TOKEN',
      // your user id for which you generated $ACCESS_TOKEN
      externalUserId: '$YOUR_USER_ID'
    },
    // function for the WebSDK callbacks
    function(messageType, payload) {
      // e.g. just logging the incoming messages
      console.log('[IDENSIC DEMO] Idensic message:', messageType, payload)
    }
  )
</script>

# WebSDK messages

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

# Errors

# 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

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

# 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 SELFIE step of Applicant request's requiredIdDocs.docSets.

Liveness enable example:

             "requiredIdDocs": {
               "docSets": [
                 {
                   "idDocSetType": "IDENTITY",
                   "types": [
                     "ID_CARD",
                     "PASSPORT",
                     "DRIVERS",
                     "RESIDENCE_PERMIT"
                   ]
                 },
                 {
                   "idDocSetType": "SELFIE",
                   "types": [ "SELFIE" ],
                   "videoRequired": "liveness"
                 }
               ]
             },

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