Назад

Работа с clientKey

clientKey — это пользовательский идентификатор, который вы сами задаёте и используете для связи KYC‑сессий с вашими пользователями, заявками или договорами.

Через clientKey вы можете:

  • находить все KYC‑сессии конкретного пользователя;
  • сопоставлять результаты проверки с вашими объектами (userId, orderId, loanId и т.п.);
  • фильтровать сессии через REST API;
  • удобнее обрабатывать вебхуки.

Важно: значение clientKey придумываете вы, платформа не генерирует его автоматически.

Формат и ограничения

  • Тип: string
  • Максимальная длина: 36 символов
  • Формат: любая строка, удобно ограничиться латиницей, цифрами и разделителями ([a-zA-Z0-9_-])

Рекомендуется использовать:

  • clientKey = userId — если одна KYC‑проверка на пользователя;
  • clientKey = "${userId}:${applicationId}" — если KYC привязана к заявке, заказу, договору;
  • clientKey = UUID — если удобнее работать только с KYC‑идентификатором.

Две формы clientKey: «сырой» и зашифрованный

Для интеграции с WebSDK нужно понимать, что есть:

  1. Исходное значение (clientKeyRaw) То, что вы придумали: например, "user_123" или "loan-42".
  2. Зашифрованное значение (clientKey) То, что вы реально передаёте в виджет. Это результат шифрования clientKeyRaw «секретным ключом сценария» в ЛК.

Схема работы:

  1. На backend:
  • формируете clientKeyRaw (до 36 символов);
  • шифруете его секретным ключом сценария;
  • отправляете зашифрованный clientKey на фронт.
  1. На frontend:
  • передаёте зашифрованный clientKey в KYCWidget.setupKYC(...).
  1. На стороне KYC‑сервиса:
  • значение расшифровывается;
  • исходный clientKeyRaw сохраняется в сессии;
  • по нему можно фильтровать сессии и получать результаты через API и вебхуки.

В API (/kyc/session/status, /kyc/sessions/filter и вебхуках) вы работаете с исходным значением, которое сами задали. Шифрование нужно только для безопасной передачи clientKey в браузер.

Где используется clientKey

В WebSDK

Вызов виджета:

window.KYCWidget.setupKYC({
  schemaId:  "SCHEMA_ID",            // ID схемы проверки
  clientKey: "ENCRYPTED_CLIENT_KEY", // зашифрованный clientKeyRaw
  theme: "light",
  closeCb:   () => console.log("CLOSE"),
  successCb: (payload) => {
    console.log("SUCCESS", payload);
    // здесь вы уже знаете исходный clientKeyRaw, т.к. сами его задавали на backend
  },
});

В REST API

  • /kyc/session/status — можно передать clientKey, чтобы уточнить статус по конкретному ключу;
  • /kyc/sessions/filter — есть фильтр clientKey, чтобы получать все сессии по ключу.

Здесь вы передаёте исходное значение (clientKeyRaw), без шифрования.

Генерация и шифрование clientKey на backend

Секретный ключ сценария (Scenario Secret Key) хранится только на вашей серверной стороне. В браузер его передавать нельзя.

Общая идея:

  1. Берёте clientKeyRaw (до 36 символов).
  2. Берёте секретный ключ сценария из ЛК (scenarioSecretKey).
  3. На backend шифруете clientKeyRaw по алгоритму (пример — AES‑256‑CBC).
  4. Получившийся Base64‑строку передаёте в WebSDK как clientKey.

Пример на Node.js (AES‑256‑CBC)

const crypto = require("crypto");

// 1. Исходный идентификатор (то, что вы хотите видеть в API и вебхуках)
const clientKeyRaw = "user_123"; // до 36 символов

// 2. Секретный ключ сценария из ЛК (НЕ передаём в браузер!)
const password = "SCENARIO_SECRET_KEY";

// 3. Получаем 32‑байтовый ключ из пароля
const key = crypto.createHash("sha256").update(password).digest('hex').substr(0, 32);

// 4. Генерируем случайный IV (16 байт)
const iv = crypto.randomBytes(16);

// 5. Шифруем clientKeyRaw
const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
const encrypted = Buffer.concat([cipher.update(clientKeyRaw, "utf8"), cipher.final()]);

// 6. Склеиваем IV + шифртекст и кодируем в Base64 — это и есть clientKey для виджета
const encryptedBase64 = Buffer.concat([iv, encrypted]).toString("base64");

console.log("clientKeyRaw:", clientKeyRaw);
console.log("clientKey (encrypted):", encryptedBase64);

Именно такой зашифрованный clientKey вы подставляете в:

window.KYCWidget.setupKYC({
  schemaId:  "SCHEMA_ID",
  clientKey: encryptedBase64,
  // ...
});

Кнопка «Проверить» рядом с секретным ключом сценария в ЛК использует тот же алгоритм шифрования и помогает быстро проверить, что clientKey шифруется/дешифруется корректно. Для продакшена всегда шифруйте на своём backend.

Как тестировать clientKey

  1. В ЛК найдите секретный ключ сценария.
  2. Нажмите кнопку «Проверить» и введите тестовый clientKeyRaw (например, test_user_1).
  3. ЛК вернёт зашифрованное значение — его можно временно подставить в примеры интеграции (вместо "ENCRYPTED_CLIENT_KEY").
  4. Убедитесь, что:
  • виджет открывается без ошибок;
  • в ваших логах KYC‑сессий видно исходное clientKeyRaw (например, в фильтрации по clientKey через /kyc/sessions/filter).

Частые вопросы и ошибки

«Где мне взять значения для clientKey и clientUser?»

  • clientKey — любая строка до 36 символов, которую вы определяете сами: userId, номер заявки, заказ, любое удобное значение. Параметр обязателен.
  • clientUser — тоже любая строка до 36 символов, но в новых интеграциях его лучше не использовать.

Правильная практика: задайте clientKeyRaw = вашему userId или orderId, зашифруйте его и передавайте только clientKey.

Ошибка в консоли: «Не удалось выполнить асимметричную расшифровку!»

Чаще всего значит, что:

  • в виджет передан незашифрованный clientKeyRaw;
  • или использован другой секретный ключ, отличный от ключа сценария;
  • или значение clientKey было повреждено/обрезано (например, при копировании).

Проверьте:

  1. Что вы передаёте в виджет именно Base64‑строку, полученную после шифрования (см. пример выше).
  2. Что сценарий в ЛК и секретный ключ, которым вы шифруете, совпадают.
  3. Что не используется лишний параметр clientUser (его можно убрать).

«А как узнать clientKey для расшифровки вебхука?»

Для расшифровки тела вебхука clientKey не нужен:

  • вебхук шифруется ключом сессии/секретом вебхука, а не clientKey;
  • для расшифровки достаточно пароля/ключа, который вы указали в настройках вебхука, и зашифрованного поля encrypted из POST‑запроса.

clientKey в вебхуке — это просто одно из полей JSON внутри уже расшифрованного тела, и его значение будет ровно тем, которое вы задавали в clientKeyRaw.

«Почему каждый тестовый вебхук приходит с разной строкой encrypted, хотя JSON один и тот же?»

Это нормально:

  • при шифровании используется случайный IV (vector инициализации);
  • даже при одинаковом JSON и ключе шифрования шифртекст каждый раз разный;
  • после расшифровки тело будет одинаковым JSON.

«Как общий статус success/failed связан с проверками и базами?»

Общий статус KYC‑сессии:

  • success — только если все проверки прошли успешно;
  • если где‑то есть failed (OCR, fraud, базы и т.д.) — общий статус будет failed.

Проверки по внешним базам (санкции, ФССП и т.п.) также влияют на общий success: если «красный флаг» считается критичным, он даст failed и на уровне всей сессии.

Рекомендованный рабочий поток с clientKey

  1. На backend при старте KYC‑процесса:
  • генерируете или выбираете clientKeyRaw (например, user_123);
  • шифруете его секретным ключом сценария → encryptedClientKey;
  • сохраняете clientKeyRaw у себя вместе с userId/orderId.
  1. На frontend:
  • передаёте encryptedClientKey в KYCWidget.setupKYC(...).
  1. Для получения результата:
  • либо принимаете вебхук и внутри тела смотрите поле clientKey;
  • либо вызываете /kyc/sessions/filter с clientKey = clientKeyRaw, чтобы найти все сессии по этому ключу.

Так вы всегда можете однозначно установить, к какому пользователю или заявке относится любая KYC‑сессия.