# How to use SumSub

This article provides instructions on how to configure B2CORE to use the KYC and KYT provider, [SumSub](https://sumsub.com/).

{% hint style="info" %}
Before proceeding with the instructions, you must have signed up for SumSub and have an active account. For KYT checks, **SumSub Fraud Prevention** must also be enabled and properly configured.
{% endhint %}

## How to configure a connection to SumSub

Only admins who are assigned the permissions to manage external connections can set up a connection to SumSub.

To set up a connection:

{% stepper %}
{% step %}
In the B2CORE Back Office, navigate to **System** > **External connections**.
{% endstep %}

{% step %}
Click **+Create** in the upper-right page corner.
{% endstep %}

{% step %}
On the **Create connection** page, fill in the following fields:

* In the **Name** field, enter a name that you want to use for the connection.
* In the **Caption** field, enter a caption that will be applied to the connection in the Back Office.
* In the **Provider** dropdown, select **SumSubstance**.
  {% endstep %}

{% step %}
Click **Save** to create the connection.
{% endstep %}

{% step %}
In the connections list, find the SumSub connection that you've created and click **Edit** to enter the connection details.
{% endstep %}

{% step %}
On the **Edit connection** page, specify the following settings:

* In the **Service Location** field, specify `https://api.sumsub.com/`.
* In the **Client ID** field, specify your SumSub account name. To view your account name, in the SumSub interface, go to **Settings** > **Account Details**.
* In the **Webhook Secret Key** field, specify a webhook secret. You should generate the webhook in the SumSub interface. To do this, in the SumSub interface, go to **Dev space** > **Webhooks** (for the required webhook configuration, refer to [SumSub webhook configuration](#sumsub-webhook-configuration)).
* Leave the **Login** and **Password** fields empty.
* In the **Token** and **Token Secret** fields, specify a token and a secret key value generated in the SumSub interface. To generate them, in the SumSub interface, go to **Dev space** > **App Tokens**.
* To apply different verification flows to *individual* and *corporate* clients, select **Enabled** in the **Client Resetting Mode** dropdown.

{% hint style="info" %}
When the **Client Resetting Mode** option is enabled, this means that repeated verification is required for clients whose type has been changed from *individual* to *corporate*, or vice versa. After changing a type, the following happens:

* In the B2CORE Back Office, a client’s verification level resets to `Level 0`, which is the default verification level.
* All pending [client’s requests](https://docs.b2core.b2broker.com/back-office-guide/clients/requests) to obtain a higher verification level are automatically rejected.
* In the SumSub system, an applicant is set back to the initial level, and all documents that have been previously uploaded for this applicant are invalidated.

All files and documents that have been previously uploaded for this client in the B2CORE Back Office will still be available.
{% endhint %}
{% endstep %}

{% step %}
In the **Transaction monitoring** section, configure the settings for KYT checks using the **SumSub Fraud Prevention**. These checks are currently supported for fiat and crypto deposits and withdrawals.

* In the **Enabled** dropdown, select:
  * **Yes** — to enable transaction monitoring via **SumSub** and receive results in B2CORE.
  * **No** — to disable transaction monitoring via **SumSub**.
* In the **Currency Filter** dropdown:
  * Select one or more currencies to monitor transactions only in the selected currencies.
  * Leave the list empty to monitor transactions in all currencies.
    {% endstep %}

{% step %}
Click **Save** to apply the settings.
{% endstep %}
{% endstepper %}

## How to create document groups for SumSub verification

Create document groups to enable clients to submit various documents supported by SumSub for verification. For each document (such as an ID card, passport, driver’s license, and others) that you want to make available for verification, create a separate document group with the appropriate name.

To create a document group:

{% stepper %}
{% step %}
In the B2CORE Back Office, navigate to **Verification** > **Document groups**.
{% endstep %}

{% step %}
Click **+Create** in the upper-right page corner.
{% endstep %}

{% step %}
On the **Create document group** page, fill in the following fields:

* In the **Name** field, specify the name of a document group.

{% hint style="info" %}
Ensure to specify document group names exactly as the names of [document types supported by SumSub](https://docs.sumsub.com/reference/add-id-documents#supported-document-types), such as `ID_CARD`, `PASSPORT`, `DRIVERS`, `RESIDENCE_PERMIT`, and so on.

For example, if you want your clients to submit their ID cards for document verification, create a document group with the name `ID_CARD`.
{% endhint %}

* In the **Caption** field, specify a document group caption that will be displayed in the B2CORE UI.
* In the **Type** dropdown, select **One**.
* In the **Description** field, specify a description for the document group that is used in the Back Office.
  {% endstep %}

{% step %}
Make sure that **Yes** is selected in the **Enabled** dropdown.
{% endstep %}

{% step %}
Click **Save** to create the document group.
{% endstep %}
{% endstepper %}

## How to create document types for SumSub verification

For each document group that you've created, create a document type.

To create a document type:

{% stepper %}
{% step %}
In the B2CORE Back Office, navigate to **Verification** > **Document Types**.
{% endstep %}

{% step %}
Click **+Create** in the upper-right page corner.
{% endstep %}

{% step %}
On the **Create document type** page, fill in the following fields:

* In the **Name** field, specify the name of a document type.

{% hint style="info" %}
Document type names must be the same as the names of the previously created document groups. For example, `ID_CARD`, `PASSPORT`, `DRIVERS`, `RESIDENCE_PERMIT`, and so on.
{% endhint %}

* In the **Caption** field, specify a document type caption that will be displayed in the B2CORE UI.
* In the **Description** field, specify a description for the document type that will be displayed in the B2CORE UI.
* In the **Group** dropdown, select a document group with which this document type must be associated.
* In the **Max files** field, specify the maximum number of files that clients can upload for this document type.
  {% endstep %}

{% step %}
In the **Status** dropdown, select **Enabled**.
{% endstep %}

{% step %}
Click **Save** to create the document type.
{% endstep %}
{% endstepper %}

## How to create verification levels for SumSub in the B2CORE Back Office

You can create verification levels or modify the existing levels to use SumSub for verification.

To create a verification level:

{% stepper %}
{% step %}
In the B2CORE Back Office, navigate to **Verification** > **Levels**.
{% endstep %}

{% step %}
Click **+Create** in the upper-right page corner.
{% endstep %}

{% step %}
On the **Create verification level** page, fill in the following fields:

* In the **Index** field, specify a non-zero integer value.

  The zero (`0`) index is always assigned to the default verification level. For other verification levels, the index must be greater than zero, such as `1` for Level 1, `2` for Level 2 and so on.
* In the **Wizard** dropdown, select `SnsWizardSDK`.
* In the **Caption** field, specify a level name that will be displayed in the B2CORE UI and mobile app, such as `Level 1`. If required, specify the localization properties for this field by clicking the button located on the right side of the field.
* In the **Desktop Description** field, specify a description of the level to be displayed in the B2CORE UI. This description can include the permissions granted to clients once they obtain this level.

  The description for the B2CORE UI can be specified in the HTML format. If required, specify the localization properties for this field.
* In the **Mobile Description** field, specify a level description to be displayed in the mobile app.

  The description for the mobile app can be specified in the JSON format. If required, specify the localization properties for this field.
* In the **Visible** dropdown, select **Yes**.
* In the **Default** dropdown, select **No**. (`Level 0` is always the default verification level).
* In the **Assigned Client Right** dropdown, select a permission level defining the set of permissions that you want to grant to your clients after obtaining this verification level (for details, refer to [Client rights](https://docs.b2core.b2broker.com/back-office-guide/system/client-rights)).
* In the **Document groups** dropdown, select one or more required document groups. For example, you can select `ID_CARD` and `RESIDENCE_PERMIT` if you want your clients to submit their ID cards and residence permits for verification to receive this level.
* In the **Client tests** dropdown, optionally select one or more accreditation tests if you want to force your clients to pass these tests before they can submit their documents for verification. The list of available tests includes all the tests with visibility set to **Yes**, which are displayed on the [Client tests](https://docs.b2core.b2broker.com/back-office-guide/verification/client-tests) page.
  {% endstep %}

{% step %}
Click **Save** to create the level.
{% endstep %}
{% endstepper %}

{% embed url="<https://www.youtube.com/embed/_B2oGBF10dQ>" %}

## How to create levels and flows in the SumSub interface

The B2CORE Back Office supports two types of clients: *individual* and *corporate*. The SumSub system provides the capability to set up a separate verification flow for each of the types. To use this option, make sure that you enabled the **Client Resetting Mode** when [configuring a connection to SumSub](#how-to-configure-a-connection-to-sumsub).

To add a new level:

{% stepper %}
{% step %}
In the SumSub interface, navigate to **Integrations** > **Applicant Levels**.
{% endstep %}

{% step %}
Click **Add new level**.
{% endstep %}

{% step %}
Select the required steps.

{% hint style="info" %}
Level names must be specified in the following formats:

* For *individual* clients: `level1`, `level2`, and so on.
* For *corporate* clients: `level3corporate`, `level4corporate`, and so on.

These formats ensure correct mapping between levels in SumSub and B2CORE. The mapping is based on the **Index** assigned to each verification level in B2CORE. You can find indexes in the respective column on the [Verification > Levels](https://docs.b2core.b2broker.com/back-office-guide/verification/levels) page of the B2CORE Back Office and use them in the level names for SumSub. For example:

* `level1` in SumSub maps to the level with **Index** = 1 in B2CORE
* `level2` in SumSub maps to the level with **Index** = 2 in B2CORE
* `level3corporate` in SumSub maps to the level with **Index** = 3 in B2CORE
* `level4corporate` in SumSub maps to the level with **Index** = 4 in B2CORE and so on.
  {% endhint %}
  {% endstep %}
  {% endstepper %}

To add a new flow:

{% stepper %}
{% step %}
In the SumSub interface, navigate to **Integrations** > **Verification Flow**.
{% endstep %}

{% step %}
Click **Add new**.
{% endstep %}

{% step %}
Select the required options. For each flow, select a compatible level.
{% endstep %}
{% endstepper %}

## SumSub webhook configuration

**Reviewed**

* Name: `REVIEWED`
* Receiver: `HTTP Endpoint`
* Target: `https://{your-Back-Office-URL}/api/v1/verification-sns/handle`
* Type: `Applicant reviewed (applicantReviewed)`
* Secret key: the secret key generated in SumSub

{% hint style="info" %}
Make sure to replace `{your-Back-Office-URL}` with the domain of your B2CORE Back Office, *not* the B2CORE UI. For example, the target for webhooks may look like this: `https://example.com/api/v1/verification-sns/handle`.
{% endhint %}