Check-Driven Integration

Integrate the Web SDK using a check-driven approach.

Overview

This guide walks you through integrating the Web SDK with ComplyCube using the check-driven approach, giving you direct control over individual verification steps.

For a quick copy-paste example, use our integration assistant.

You’re viewing the check-driven SDK guide - an approach that provides detailed control but is best suited for partners or advanced use cases. We recommend using workflow integration for most implementations.

Integration flow

The Web SDK runs as part of your frontend but relies on your backend to create secure tokens. Here’s how it works:

Create a client

Generate an SDK token

Your backend requests a JWT token tied to that client.

Import and mount the SDK

Add the JS and CSS files, then mount the SDK in your web app.

Capture documents, videos, and selfies

The SDK guides your customer through the required steps.

Perform verification checks

Captured data is securely sent to ComplyCube for verification checks, and results are delivered in real time through the API or webhooks.

Integration guide

Create a client

Every verification flow starts with a client (i.e. customer). Use the API to create the client.

Example request

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "[email protected]",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const client = await complycube.client.create({
  type: "person",
  email: "[email protected]",
  personDetails: {
    firstName: "John",
    lastName: "Doe"
  }
});

from complycube import ComplyCubeClient
cc_api = ComplyCubeClient(api_key='<YOUR_API_KEY>')

new_client = {
    'type':'person',
    'email':'[email protected]',
    'personDetails': {
        'firstName':'John',
        'lastName':'Doe'
    }
}

client = cc_api.clients.create(**new_client)

use ComplyCube\ComplyCubeClient;

$ccapi = new ComplyCubeClient('<YOUR_API_KEY>');

$result = $ccapi->clients()->create([
    'type' => 'person',
    'email' => '[email protected]',
    'personDetails' => [
        'firstName' => 'John',
        'lastName' => 'Doe'
    ]
]);

using ComplyCube.Net;
using ComplyCube.Net.Resources.Clients;

var clientApi = new ClientApi(new ComplyCubeClient("<YOUR_API_KEY>"));
var newClient = new ClientRequest {
  type = "person",
  email = "[email protected]",
  personDetails = new PersonDetails {
    firstName = "John",
    lastName = "Doe"
  }
}

var client = await clientApi.CreateAsync(newclientRequest);

Example response

The response will contain an id (the Client ID). It is required for the next step.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "[email protected]",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe",
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

See Clients API Reference to learn more.

Generate an SDK token

Your backend must create an SDK token for each new flow. This token links the SDK session to the client. Tokens are short-lived and must not be reused.

Example request

curl -X POST https://api.complycube.com/v1/tokens \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "clientId":"CLIENT_ID",
          "referrer": "https://www.example.com/*"
        }'

const { ComplyCube } = require("@complycube/api");

const complycube = new ComplyCube({ apiKey: "<YOUR_API_KEY>" });

const token = await complycube.token.generate("CLIENT_ID", {
    referrer: "https://www.example.com/*"
});

using ComplyCube.Net;
using ComplyCube.Net.Resources.SDKTokens;

var sdkTokenApi = new SDKTokenApi(new ComplyCubeClient("<YOUR_API_KEY>"));

var sdkTokenRequest = {
  clientId = "CLIENT_ID",
  referrer = "https://www.example.com/*"
}

var sdkToken = await sdkTokenApi.GenerateToken(sdkTokenRequest);

Example response

{
    "token": "<CLIENT_TOKEN>"
}

See SDK Token API Reference to learn more.

Import the SDK

To import our Web SDK, you need to include it in your target page HTML:

<!DOCTYPE html>
<html>
  <head>
    ...
    <!-- Importing the Javascript library -->
    <script src="complycube.min.js"></script>

    <!-- Importing the default CSS -->
    <link rel="stylesheet" href="style.css" />
  </head>
  <body>
     <!-- This is where the Web SDK will be mounted -->
    <div id="complycube-mount"></div>
  </body>
</html>

Loading the SDK with Integrity (Optional)

For additional security, you can optionally load the ComplyCube Web SDK using Subresource Integrity (SRI). This allows the browser to verify that the JavaScript and CSS files have not been modified by validating them against cryptographic checksums.

Retrieve the latest SDK integrity values

To ensure you always use the latest supported SDK version and integrity hashes, retrieve the asset metadata from the Web SDK info endpoint.

Example request

curl -X POST https://api.complycube.com/v1/webSdk/latest \
     -H 'Authorization: <YOUR_API_KEY>'

Example response

The response includes the URLs and corresponding integrity values for both the JavaScript and CSS assets.

{
  "js": {
    "url": "<JAVASCRIPT_ASSET_URL>/complycube.min.js",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  },
  "css": {
    "url": "<CSS_ASSET_URL>/style.css",
    "integrity": "sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
  }
}

Import the SDK using integrity attributes

Use the returned values to load the SDK in your HTML with integrity and crossorigin attributes:

<!DOCTYPE html>
<html>
  ...
  <head>
    <!-- Importing the Javascript library -->
    <script
      src="<JAVASCRIPT_ASSET_URL>/sdk.min.js"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
    </script>

    <!-- Importing the default CSS -->
    <link
      rel="stylesheet"
      href="<CSS_ASSET_URL>/style.css"
      integrity="sha384-<INTEGRITY_HASH_1> sha384-<INTEGRITY_HASH_2>"
      crossorigin="anonymous">
  </link>
  </head>
  
  <!-- This is where the Web SDK will be mounted -->
  <body>
    <div id="complycube-mount"></div>
  </body>
</html>

Notes

Using SRI is optional, but recommended for environments with stricter security requirements.
The crossorigin="anonymous" attribute is required when using SRI with assets served from a different origin.
Integrity values may change when the SDK is updated. Always retrieve the latest values from the endpoint.

The links to complycube.min.js and style.css can be found in your developers portal.

Mount the SDK

With the generated SDK token, the Web SDK can be initialised in your frontend using the following Javascript code:

ComplyCube.mount({
  token: '<YOUR_WEB_SDK_TOKEN>',
  containerId: 'complycube-mount',
  stages: [
    'intro',
    'documentCapture',
    {
      name: 'faceCapture',
      options: {
        mode: 'video'
      }
    },
    'completion'
  ],
  onComplete: function(data) {
    // Using the data attributes returned, request your
    // backend server to perform the necessary ComplyCube checks
    console.info('Capture complete');
  },
  onModalClose: function() {
    // Handle the modal closure attempt
  },
  onError: function ({ type, message }) {
    if (type === 'token_expired') {
      // Request a new SDK token
    } else {
      // Handle other errors
      console.err(message);
    }
  }
});

The SDK mount parameters are described in the SDK settings section below.

Referrer policy

To enable successful communication between the SDK and our servers, your web page's Referrer Policy header should be set to strict-origin-when-cross-origin. This ensures that the referrer information is securely transmitted during HTTP requests.

You can either do it programmatically or add it directly to the web page as follows: <meta name="referrer" content="strict-origin-when-cross-origin">

Perform checks

Using the data returned by the SDK, via the onComplete callback, you can now instruct your backend server to run the appropriate checks using the create a check endpoint.

For instance, use:

documentCapture.documentId to run a document check.
documentCapture.documentId and faceCapture.livePhotoId to run an identity check.
documentCapture.documentId and faceCapture.liveVideoId to run an enhanced identity check.
poaCapture.documentId to run a proof of address check.

If you have set up webhooks as described in our webhooks guide, you will be notified once a check completes.

To retrieve the check results, you can perform a get check request.

Example request

curl -X GET https://api.complycube.com/v1/checks/{:checkId} \
     -H 'Authorization: <YOUR_API_KEY>'

SDK reference

This section describes all configurable settings, callbacks, lifecycle methods, and branding options available in the ComplyCube Web SDK.

Settings

Option

Description

token

The SDK token generated by your backend. This is required. Type: string

containerId

The ID of the container element where the SDK mounts. This must be an empty element.

Type: string Default value: complycube-mount

useModal

This defines whether the UI screens load into a modal instead of inline. Type: boolean Default value: true

disableClientAnalytics

This defines whether we track client analytics or not.

Type: boolean Default value: false

stages

This is the list of stages your clients will go through. Stages can be provided as strings or as objects. See Stages below to learn more.

Type: array[object] or array[string]

Default values: ['intro', 'faceCapture, 'documentCapture', 'completion']

language

The UI language. Valid values include:

en , ar, br, de, es, fr, hi, hk, id, it, ja, ko, nl, no, pl, pt, sv, th, vi, zh

Type: string Default value: en

Callback

Callbacks let you respond to SDK lifecycle events.

Option

Description

onComplete

Triggered after the client completes the verification flow. Typically used to trigger a check on your backend.

Depending on the stages provided, data may include the following attributes:

documentCapture
- documentId: ID of the captured document.
- documentType: Type of document uploaded.
faceCapture
- liveVideoId: ID of the captured video. OR;
- livePhotoId: ID of the captired photo.
poaCapture
- documentId: ID of the uploaded proof of address document.
- documentType: Type of the uploaded proof of address document.

onError

Triggered when an error occurs. The error object has two attributes:

type: This can be:
- exception
- token_expired : indicates the token has expired. When this occurs, a new SDK token must be provided.
message: Description of the error.

onExit

This callback is triggered when your client exits before completing the flow. It will return the exit reason, e.g., USER_CONSENT_NOT_GRANTED.

onModalClose

Triggered when the client tries to close the modal. You can allow or prevent closure by updating the isModalOpen attribute using updateSettings.

Updating settings

A number of settings can be updated at runtime as follows:

complycube = ComplyCube.mount({...});

// Replace the SDK token
complycube.updateSettings({ token: "NEW_SDK_TOKEN" });
...
// Open the modal
complycube.updateSettings({ isModalOpen: true });

//Close the modal
complycube.updateSettings({ isModalOpen: false });

Unmounting the SDK

If you are using the SDK in a Single Page Application (SPA), you can call the unmount function to remove the SDK and reset its state.

complycube = ComplyCube.mount({...});
...
complycube.unmount()

Stages

The stages array defines the verification flow. Each stage can be passed as a string or as an object with options.

Supported stage names

intro: Welcome screen.
userConsentCapture: Capture customer consent.
documentCapture: Capture ID documents.
faceCapture: Capture selfies or liveness videos.
poaCapture: Capture proof of address document.
completion: End of flow.

When userConsentCapture is enabled, always handle the onExit callback if the client declines consent.

Please make sure you pass the clientConsent parameter when consent is granted by your client.

When a stage is passed as object, it will have two attributes, name and options.

Name

This is the stage name

Options

This allows you to customize each stage as follows:

Stage Name

Options

intro

heading: Change the intro screen heading.
message: A list of messages to display on the intro screen. Max size 3.
startButtonText: Change the text of the start button on the intro screen.

documentCapture

crossDeviceOnly: A boolean that indicates whether to force users to capture their document using their phone. This removes the document upload option.
documentTypes: The list of ID document types visible to the user. Valid document types include:
- passport
- driving_license
- national_identity_card
- residence_permit
Each value can be either a boolean or a country object. A boolean toggles the visibility of the document type, while a country object specifies the issuing country for non-passport documents, bypassing the country selection screen. The country value is the two-letter country ISO code.

faceCapture

mode: The mode of the facial capture. Possible values are: photo or video.

poaCapture

documentTypes: The list of Proof of Address (POA) document types visible to the client. Valid POA document types include:
- bank_statement
- utility_bill

The value of each document type is a boolean that toggles the visibility of the document type.

completion

heading: Change the completion screen heading.
message: A message to display on the completion screen. Max size 1.

Example options object

stages: [
  {
    name: "intro",
    options: {
      heading: "We need to verify your identity",
      message: [
        "In order to open an account, we need to check a few things.",
        "This will take only a moment",
      ],
      startButtonText: "Start Verification"
    },
  },
  "userConsentCapture",
  {
    name: "documentCapture",
    options: {
      crossDeviceOnly: true,
      documentTypes: {
        passport: true,
        driving_license: false,
        national_identity_card: true,
        residence_permit: {
          country: "GB",
        },
      },
    },
  },
  {
    name: "faceCapture",
    options: {
      mode: "video"
    },
  },
  {
    name: "poaCapture",
    options: {
      documentTypes: {
        bank_statement: true,
        utility_bill: false,
      },
    },
  },
  {
    name: "completion",
    options: {
      heading: "Thank you for completing the process",
      message: ["we will get in touch shortly"]
    },
  }
];

Branding

You can customise the SDK’s look and feel with the branding object. It comprises of the attributes outlined below.

Appearance

The appearance object allows you to customize the color scheme of the SDK with CSS values (e.g. RGBA, Hex). Customizable attributes include:

Attribute

Description

infoPopupColor

Warning popup background color.

infoPopupTextColor

Warning popup background color.

infoPopupLinkHoverColor

Warning popup fallback Link on hover background color.

infoPopupLinkActiveColor

Warning popup fallback Link active background color.

errorPopupColor

Error popup background color.

errorPopupTextColor

Error popup text color.

errorPopupLinkHoverColor

Error popup fallback Link on hover background color.

errorPopupLinkActiveColor

Error popup fallback Link active background color.

cameraButtonHoverColor

Camera button on hover background color.

cameraButtonActiveColor

Camera button active background color.

iconButtonActiveColor

Icon button active background color.

iconButtonHoverColor

Icon button on hover background color.

primaryButtonColor

Primary button background color.

primaryButtonTextColor

Primary button text color.

primaryButtonActiveColor

Primary button active background color.

primaryButtonHoverColor

Primary button on hover background color.

primaryButtonBorderColor

Primary button border color.

secondaryButtonColor

Secondary button background color.

secondaryButtonTextColor

Secondary button text color.

secondaryButtonActiveColor

Secondary button active background color.

secondaryButtonHoverColor

Secondary button on hover background color.

secondaryButtonBorderColor

Secondary button border color.

documentSelectorColor

Document selector background color.

documentSelectorTextColor

Document selector text color.

documentSelectorActiveBorderColor

Document selector active background color.

documentSelectorHoverBorderColor

Document selector on the hover background color.

linkHoverColor

Link on the hover background color.

linkActiveColor

Link active background color.

linkUnderlineColor

Link underline color.

linkHoverTextColor

Link on the hover text color.

bodyTextColor

SDK content text color.

headingTextColor

SDK heading text color.

subheadingTextColor

SDK subheading text color.

Logo

The logo object has the following attributes:

lightLogoUrl: URL for your logo's light version.
darkLogoUrl: URL for your logo's dark version.

Example of logo branding

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  logo: {
    lightLogoUrl: 'light_logo_url',
    darkLogoUrl: 'dark_logo_url',
  }
},

Text Brand

The textBrand attribute represents the textual format of your brand.

Example of text branding

branding: {
  appearance: {
    primaryButtonColor: '#FF0000',
  },
  textBrand: 'Acme Bank'
}

If logo and textBrand attributes are specified at the same time, logo takes precedence.

Good evening

hashtagOverview

hashtagIntegration flow

hashtagCreate a client

hashtagGenerate an SDK token

hashtagImport and mount the SDK

hashtagCapture documents, videos, and selfies

hashtagPerform verification checks

hashtagIntegration guide

hashtagCreate a client

hashtagGenerate an SDK token

hashtagImport the SDK

hashtagRetrieve the latest SDK integrity values

hashtagImport the SDK using integrity attributes

hashtagNotes

hashtagMount the SDK

hashtagReferrer policy

hashtagPerform checks

hashtagSDK reference

hashtagSettings

hashtagCallback

hashtagUpdating settings

hashtagUnmounting the SDK

hashtagStages

hashtagSupported stage names

hashtagName

hashtagOptions

hashtagExample options object

hashtagBranding

hashtagAppearance

hashtagLogo

hashtagExample of logo branding

hashtagText Brand

hashtagExample of text branding

Overview

Integration flow

Create a client

Generate an SDK token

Import and mount the SDK

Capture documents, videos, and selfies

Perform verification checks

Integration guide

Create a client

Generate an SDK token

Import the SDK

Retrieve the latest SDK integrity values

Import the SDK using integrity attributes

Notes

Mount the SDK

Referrer policy

Perform checks

SDK reference

Settings

Callback

Updating settings

Unmounting the SDK

Stages

Supported stage names

Name

Options

Example options object

Branding

Appearance

Logo

Example of logo branding

Text Brand

Example of text branding