Sumsub

This document describes the process of integrating Sumsub's Know Your Customer (KYC) service into the Orangepill platform. It outlines the prerequisites, required configurations on both platforms.

Prerequisites

Before Sumsub can be used as a KYC provider in Orangepill, you must complete the following setup steps:

1. Identify the Realm Key (Source Key)

In Orangepill, each company is associated with a realm, which acts as a logical grouping for identities and integrations. When a company is created:

• A realm is automatically created in Orangepill.

• A unique realm key (UUID) is generated and assigned to that realm.

This realm key will serve as the source key for integrating with Sumsub and must be used when creating related entities (e.g., webhooks, app tokens, applicants) within Sumsub.

Example Realm Key: e69ea64e-64d1-4d64-8c5c-806923a537a8

2. Create a Webhook in Sumsub

Configure a webhook in Sumsub to notify Orangepill about applicant status changes. Make sure to use the webhook type:

applicantReviewed

This webhook is triggered whenever an applicant's review status changes (e.g., approved, rejected).

Webhook URL Format:

https://proxy.orangepill.cloud/v1/kycs/session/notify/sumsub/<realm-key>

After setting up the webhook:

• Select the applicantReviewed type.

• Copy the Webhook Secret Key — this will be used by Orangepill to verify the authenticity of incoming webhook requests via HMAC signature.

• Assign the Realm Key as the Source Key in Sumsub — this links the webhook to a specific realm and ensures only users/applicants within that context trigger notifications.

3. Generate App Token and Secret Key

In Sumsub, generate an App Token scoped to the same realm (using the realm key as the source). This process returns:

• app_token: Used for authenticating API calls from Orangepill to Sumsub.

• secret_key: Used to sign requests.

This app_token and secret_key pair must also be stored alongside the realm’s configuration in Orangepill.

---

Registering the Sumsub Provider in Orangepill

Once the necessary credentials have been collected, you can register Sumsub as a KYC provider within Orangepill using the internal API.

Example API Request

curl --location 'https://api.orangepill.cloud/v1/kycs' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "provider": "sumsub",
    "base_url": "https://api.sumsub.com",
    "credentials": {
        "app_token": "<APP_TOKEN>",
        "secret_key": "<SECRET_KEY>",
        "webhook_secret": "<WEBHOOK_SECRET>"
    },
    "data": {
        "allow_session_storage": true
    }
}'

Field Descriptions

Field	Description
provider	The name of the provider. Must be "sumsub".
base_url	Sumsub API base URL. Usually https://api.sumsub.com.
credentials.app_token	Token issued by Sumsub to identify your application.
credentials.secret_key	Used to sign and verify Sumsub requests.
credentials.webhook_secret	Secret for verifying webhook payloads from Sumsub.
data.allow_session_storage	If true, allows Orangepill to store applicantId on the associated identity.

Successful Response:

{
    "id": "<PROVIDER_ID>",
    "provider": "sumsub",
    "data": {
        "allow_session_storage": true
    },
    "baseUrl": "https://api.sumsub.com",
    "createdAt": 1752855581224,
    "deleted": false
}

---

Retrieve a Registered KYC Provider

Once a KYC provider (e.g., Sumsub) has been registered in Orangepill, you can retrieve its configuration using the provider’s unique identifier.

API: Get KYC Provider by ID

Request:

curl --location 'https://api.orangepill.cloud/v1/kycs/<PROVIDER_ID>' \
--header 'x-api-key: <API_KEY>'

• Replace <provider_id> with the ID returned during provider registration.

• Replace <API_KEY> with a valid Orangepill API key.

---

Successful Response:

{
  "id": "<PROVIDER_ID>",
  "provider": "sumsub",
  "data": {
    "allow_session_storage": true
  },
  "baseUrl": "https://api.sumsub.com",
  "createdAt": 1752512730707,
  "deleted": false
}

---

Create a KYC Verification Session

Once the provider has been registered and configured, you can initiate a KYC verification session for a user by creating an applicant in Sumsub through Orangepill’s API.

Orangepill will generate a Sumsub applicant using the user’s identity ID (used as the external user ID), and return a session token that can be used to launch the Sumsub SDK or WebApp.

API: Create Sumsub KYC Session

Endpoint:

POST /v1/kycs/session/sumsub

Request:

curl --location 'https://api.orangepill.cloud/v1/kycs/session/sumsub' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "parameters": {
        "level_name": "basic-kyc-level",
        "external_user_id": "<IDENTITY_ID>"
    }
}'

Request Body Parameters

Field	Description
level_name	The verification level configured in your Sumsub dashboard (e.g., basic-kyc-level).
external_user_id	The ID of the identity in Orangepill. This will be mapped to Sumsub’s externalUserId for the applicant.

Successful Response:

{
    "id": "<APPLICANT_ID>",
    "externalUserId": "<IDENTITY_ID>",
    "sourceKey": "<REALM_KEY>",
    ...
}

---

Upload Verification Files for an Applicant

Once a Sumsub applicant has been created, the next step is to upload the necessary verification files (e.g., selfies, ID front/back images) using Orangepill’s unified API.

This endpoint allows the platform to send document files to Sumsub on behalf of the user.

API: Upload Verification File

Endpoint:

POST /v1/kycs/verification/sumsub/file

Request:

curl --location 'https://api.orangepill.cloud/v1/kycs/verification/sumsub/file' \
--header 'x-api-key: <API_KEY>' \
--form 'applicantId="687a4fe322f276e950dcc5fc"' \
--form 'idDocType="SELFIE"' \
--form 'idDocSubType="FRONT_SIDE"' \
--form 'country="RUS"' \
--form 'content=@"/selfie.png"' \
--form 'firstName="JOHN"' \
--form 'lastName="WICK"'

Request Form Parameters

Field	Description
applicantId	The Sumsub applicant ID obtained from the session creation step.
idDocType	Type of document being uploaded. Common values: PASSPORT, ID_CARD, DRIVERS, SELFIE.
idDocSubType	Document side or subcategory. E.g., FRONT_SIDE, BACK_SIDE, or leave blank for SELFIE.
country	3-letter ISO 3166-1 alpha-3 country code (e.g., DEU for Germany).
content	The actual image or PDF file to upload. Must be a binary file (e.g., PNG, JPEG).
firstName	Applicant's first name (used by Sumsub to enrich data).
lastName	Applicant's last name (used by Sumsub to enrich data).

⚠️ The file size must comply with Sumsub’s upload restrictions (typically < 50MB per file).

Behavior

• This endpoint uploads the document to Sumsub on behalf of the applicant.

• Multiple documents can be uploaded using separate requests (e.g., front and back of ID card).

• If a required field is missing or the document is invalid, Sumsub will reject the upload and respond with an error.

Successful Response:

{
    "idDocType": "SELFIE",
    "country": "RUS"
    "firstName": "JOHN",
    "lastName": "WICK"
}

---

Submit Document Metadata Without File Upload

In some cases, it's necessary to send document-related information without uploading a file. This could include updating document details, enriching metadata, or triggering verification when documents are submitted through alternative channels.

Orangepill provides a dedicated endpoint to send applicant metadata to Sumsub, independent of file uploads.

API: Submit Verification Info

Endpoint:

bashCopyEditPOST /v1/kycs/verification/sumsub/info

Request:

bashCopyEditcurl --location 'https://api.orangepill.cloud/v1/kycs/verification/sumsub/info' \
--header 'x-api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "applicantId": "6877fa681a4796e48f32b888",
    "idDocType": "PASSPORT",
    "idDocSubType": "FRONT_SIDE",
    "firstName": "PETER",
    "lastName": "SULLIVAN",
    "country": "ZAF",
    "placeOfBirth": "ZAF"
}'

Behavior

• This endpoint sends applicant metadata to Sumsub.

• It does not include any file content.

• Can be used before or after file uploads to keep data up to date.

• Useful for compliance workflows where document info is verified separately.