Skip to main content

Sumsub - Automatic KYC

The sumsub plugin lets your users verify their identity with Sumsub from the Verification page on your exchange. It is an opt-in alternative to HollaEx's built-in Automatic KYC: it replaces that flow, and you use and pay for your own Sumsub account.

What you need​

  • The Enterprise plan on HollaEx Cloud.
  • Your own Sumsub account, with an app token and a secret key.
  • A verification level in Sumsub named exactly basic-kyc-level. The plugin always uses this level name.
  • No other KYC plugin. Only one KYC plugin can be installed at a time, so remove automatic-kyc (or any other KYC plugin) first.

Set it up​

  1. Get your Sumsub credentials. In your Sumsub dashboard, create an app token and secret key, and make sure the basic-kyc-level level exists.

  2. Install the plugin. Go to Operator Controls → Exchange → Plugins, find sumsub under Available to install and click Install.

  3. Configure it. Open the plugin with Configure, fill in the settings and save.

    SettingWhat it does
    tokenYour Sumsub app token. Secret, from Sumsub. Required.
    secretYour Sumsub secret key. Secret, from Sumsub. Required.
    webhook_secretThe secret key you set on the webhook in Sumsub (step 4). Every webhook is checked against it. Secret. Required.
    urlSumsub's API address. Leave the default, https://api.sumsub.com.

  4. Add the webhook in Sumsub. In the Sumsub dashboard, under Dev space → Webhooks, add a webhook pointing to your exchange's API address followed by /plugins/sumsub/webhook. Use this address, with your exchange's API domain in place of <your-api-domain>:

    https://<your-api-domain>/plugins/sumsub/webhook

    Choose a secret key for the webhook and enter the same value as webhook_secret in the plugin. Your API domain depends on how your exchange is set up, for example api.yourexchange.com or yourexchange.com/api. See Base URLs to check yours, or open a ticket.

  5. Check the webhook address. Open the webhook URL in a browser. It shows a message confirming the endpoint is active.

  6. Test it. Sign in to your exchange as a test user, open Verification and complete a Sumsub check.

What your users see​

On the Verification page, users click a button to start the identity check and complete it in Sumsub's flow. The page then shows that the check is being processed, approved or failed. A user whose check failed can try again.

How it works​

  • Sumsub tells your exchange about each result through the webhook. A green review sets the user to verified; a red one sets them to rejected.
  • Before changing a user's status, the plugin checks the webhook's signature and then asks Sumsub's API for the current result. A webhook without a valid signature, or one that doesn't match what Sumsub's API says, changes nothing.
  • Verified users are not moved to a higher tier by this plugin. Use tiers, or a tier upgrade plugin, to decide what verified users can do.
  • In Operator Controls, admins can view a user's documents, verify or revoke them, and re-pull their identity details from Sumsub. Re-pulling only fills in identity details; it never changes the verification status.
  • A user you revoke stays revoked until Sumsub completes a newer review or an admin verifies them.
  • Document images open through links that expire after 15 minutes.

Troubleshooting​

  • Users finish Sumsub but their status never changes. Check that the webhook URL is correct and that webhook_secret matches the secret set on the webhook in Sumsub exactly. Without the right secret, every webhook is refused.
  • Users can't start the check. Check token and secret, and that the basic-kyc-level level exists in your Sumsub account.

Need help? Open a ticket from your HollaEx dashboard.