Интеграция с сервером

Что делает ваш бэкенд для мобильной сессии: разрешает приложение на сервере «Нейровижн», передаёт приложению значения сессии, выпускает ключ клиента и получает вердикт от «Нейровижн».

Значения, нужные сессии

KycRequest на всех платформах принимает одни и те же значения:

ЗначениеЧто этоОткуда берётся
apiHostАдрес KYC API «Нейровижн»«Нейровижн» отправляет его вам индивидуально; он одинаков для всех ваших сессий
schemaId + clientKeyВаш сценарий и зашифрованный идентификатор этой проверкиschemaId — ID сценария из раздела «KYC/AML» личного кабинета (в Web SDK этот же параметр называется scenarioId); clientKey шифрует ваш сервер (см. ниже «Выпуск ключа клиента»)
или taskIdИдентификатор задачи верификацииНужен, только если вам выдали ссылку на задачу вида https://kyc.neuro-vision.ru/<taskId>; при обычной интеграции используются schemaId и clientKey
clientUserИдентификатор пользователя в вашей системе, необязательноПередаётся открытым текстом, без шифрования, до 36 символов. Одно значение во всех попытках одного человека объединяет их в группу; по нему можно удалить данные всех сессий человека. Персональные данные не передавайте — см. Идентификаторы проверки

apiHost должен быть https. Обычный http допускается только для самого устройства (localhost), при локальной разработке.

Типичный сценарий:

  1. Приложение запрашивает у вашего бэкенда сессию проверки.
  2. Бэкенд выбирает clientKey для этой проверки, шифрует его (или создаёт задачу) и возвращает schemaId + clientKey (или taskId), а при необходимости и clientUser. apiHost можно вернуть вместе с ними или хранить в конфигурации приложения.
  3. Приложение передаёт их в KycRequest и запускает SDK.
  4. Когда сессия закончится, бэкенд получает её вердикт от «Нейровижн» и принимает решение.

Разрешение приложения на сервере

Сервер «Нейровижн» пускает только те адреса (origins), которые есть в его списке. Сайт приходит со своим доменом, а мобильное приложение — со своим id: Application ID на Android, Bundle Identifier на iOS.

Временно адрес приложения записывается с префиксом https://: https:// + id приложения, например https://com.example.mykyc. Позже для приложений появится отдельный тип записи — мы сообщим.

  • Добавьте адрес сами в личном кабинете: «Доступ» → «Разрешённые домены», туда же, где домены сайта.
  • Каждая сборка — свой адрес: debug-сборке с applicationIdSuffix или iOS-приложению с bundle id, отличным от Android, нужна своя запись.
  • Если адреса нет в списке, проверка сразу останавливается с сообщением «Проверка недоступна на этом домене. Обратитесь к администратору сайта.»

Пошагово, с примерами для каждой платформы — Быстрый старт, шаг 1.

Выпуск ключа клиента

clientKey — уникальная строка для каждой попытки проверки, до 36 символов. Значение придумываете вы, например UUID или u1024:o77:1 (пользователь : заявка : номер попытки). По нему вы потом найдёте сессию в API и вебхуках.

В приложение clientKey попадает только в зашифрованном виде: ваш сервер шифрует его секретным ключом сценария, «Нейровижн» расшифровывает и сохраняет в сессии исходное значение. Ни секрет, ни код шифрования в приложение не попадают. Шифрование то же, что и в Web SDK, — см. Работа с clientKey.

Один clientKey — одна сессия. Из-за случайного IV зашифрованный ключ каждый раз выглядит по-новому, но сессию сервер ищет по исходному значению. Запуск с уже использованным clientKey откроет прежнюю сессию, поэтому каждую новую попытку, в том числе повторную проверку того же человека, запускайте с новым clientKey. Попытки одного человека объединяет clientUser: передавайте в нём один и тот же идентификатор пользователя. Связь «попытка → пользователь» храните и у себя: по ней вы сопоставите вебхук с человеком. Подробнее — Идентификаторы проверки.

ЧастьЗначение
Открытый текстВаш clientKey этой попытки, строка до 36 символов, например u1024:o77:1
Ключ шифрованияПервые 32 шестнадцатеричных символа SHA-256(секретного ключа сценария), взятые как 32 байта ASCII
ШифрAES-256-CBC, дополнение PKCS#7, случайный 16-байтовый IV
Результатbase64(IV ‖ шифротекст)

Не передавайте в clientKey персональные данные — ни ФИО, ни телефон, ни email, ни номер документа. Используйте собственный непрозрачный идентификатор, например UUID или внутренний номер заявки.

Node.js (встроенный 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 (пакет cryptography):

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"])

Проверить шифрование можно кнопкой «Проверить» рядом с секретным ключом сценария в личном кабинете: она шифрует значение тем же алгоритмом.

Передавайте зашифрованный ключ приложению как есть.

Вердикт

Приложение получает вердикт для следующего экрана (см. Результаты). Важное решение — открытие счёта, лимит платежей — должно опираться на результат сессии, который ваш сервер получает от «Нейровижн» по вебхуку или запросом статуса сессии, а не на то, что сообщает приложение.