Server integration

What your backend does for a mobile session: allows the app on the NeuroVision server, gives the app the session's values, mints the client key, and gets the verdict from NeuroVision.

The values a session needs

Every platform's KycRequest takes the same values:

ValueWhatWhere it comes from
apiHostThe URL of the NeuroVision KYC APINeuroVision sends it to you individually; it is the same for all your sessions
schemaId + clientKeyYour scenario and the encrypted identifier of this verificationschemaId — the scenario ID from the “KYC/AML” section of your dashboard (the Web SDK calls the same parameter scenarioId); clientKey is encrypted by your server (see section “Minting the client key” below)
or taskIdThe ID of a verification taskNeeded only if you were given a task link of the form https://kyc.neuro-vision.ru/<taskId>; a regular integration uses schemaId and clientKey
clientUserThe user’s ID in your system, optionalPassed as plain text, unencrypted, up to 36 characters. The same value in all attempts of one person groups them; it lets you delete the data of all of that person’s sessions. Do not pass personal data — see Working with clientKey

apiHost must be https. Plain http is accepted only for the device itself (localhost), for local development.

A typical flow:

  1. The app asks your backend for a verification session.
  2. Your backend picks a clientKey for this verification, encrypts it (or creates a task) and returns schemaId + clientKey (or taskId), plus clientUser if needed. The apiHost can be returned with them or kept in the app's configuration.
  3. The app passes them to KycRequest and starts the SDK.
  4. When the session ends, your backend gets its verdict from NeuroVision and makes the decision.

Allowing your app on the server

The NeuroVision server lets in only the addresses (origins) on its list. A website comes with its domain; a mobile app comes with its id: the Application ID on Android, the Bundle Identifier on iOS.

For now an app's address is written with the https:// prefix: https:// + the app's id, e.g. https://com.example.mykyc. Later apps will get a separate kind of entry; we will let you know.

  • Add the address yourself in your dashboard: "Access" → "Allowed domains", where the website's domains are.
  • Every build is its own address: a debug build with an applicationIdSuffix, or an iOS app whose bundle id differs from the Android one, needs its own entry.
  • An address missing from the list stops the check at once with "Verification is not available on this domain. Please contact the site administrator."

Step by step, with examples for each platform — Quick start, step 1.

Minting the client key

clientKey is a unique string for each verification attempt, up to 36 characters. You choose the value, for example a UUID or u1024:o77:1 (user : order : attempt number). Later you use it to find the session in the API and webhooks.

clientKey reaches the app only in encrypted form: your server encrypts it with the scenario secret key, and NeuroVision decrypts it and stores the original value in the session. Neither the secret nor the encryption code goes into the app. The encryption is the same as in the Web SDK — see Working with clientKey.

One clientKey — one session. Because of the random IV, the encrypted key looks different every time, but the server looks up the session by the original value. Starting with a clientKey that was already used opens the earlier session, so start every new attempt, including a repeat verification of the same person, with a new clientKey. A person's attempts are grouped by clientUser: pass the same user ID in it every time. Keep the "attempt → user" link on your side too: it lets you match a webhook to the person. More details — Working with clientKey.

PartValue
PlaintextYour clientKey for this attempt, a string of up to 36 characters, e.g. u1024:o77:1
Encryption keyThe first 32 hex characters of SHA-256(scenario secret key), taken as 32 ASCII bytes
CipherAES-256-CBC, PKCS#7 padding, a random 16-byte IV
Resultbase64(IV ‖ ciphertext)

Do not put personal data into clientKey — no full name, phone number, email or document number. Use your own opaque identifier, such as a UUID or an internal order number.

Node.js (built-in crypto):

const crypto = require('node:crypto');

function encryptClientKey(clientKeyRaw, secret) {
  const key = Buffer.from(crypto.createHash('sha256').update(secret, 'utf8').digest('hex').slice(0, 32), 'ascii');
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  return Buffer.concat([iv, cipher.update(clientKeyRaw, 'utf8'), cipher.final()]).toString('base64');
}

const clientKey = encryptClientKey('u1024:o77:1', process.env.KYC_SCENARIO_SECRET);

Python (the cryptography package):

import base64, hashlib, os
from cryptography.hazmat.primitives import padding
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

def encrypt_client_key(client_key_raw: str, secret: str) -> str:
    key = hashlib.sha256(secret.encode("utf-8")).hexdigest()[:32].encode("ascii")
    iv = os.urandom(16)
    padder = padding.PKCS7(128).padder()
    padded = padder.update(client_key_raw.encode("utf-8")) + padder.finalize()
    encryptor = Cipher(algorithms.AES(key), modes.CBC(iv)).encryptor()
    return base64.b64encode(iv + encryptor.update(padded) + encryptor.finalize()).decode("ascii")

client_key = encrypt_client_key("u1024:o77:1", os.environ["KYC_SCENARIO_SECRET"])

You can check your encryption with the "Check" button next to the scenario secret key in your dashboard: it encrypts a value with the same algorithm.

Pass the encrypted key to the app as is.

The verdict

The app gets the verdict for the screen that follows (see Results). A decision that matters — opening an account, a payment limit — should rest on the session result that your server gets from NeuroVision by webhook or with a session status request, not on what the app reports.