Частые вопросы о платформе NeuroVision KYC

Платформа NeuroVision KYC позволяет компаниям дистанционно проверять личность пользователей. Она объединяет распознавание документов, сравнение лица с фотографией в документе, проверку Liveness и антифрод-проверки в один процесс KYC (Know Your Customer). Состав проверок задаётся сценарием, который вы настраиваете в личном кабинете.

Платформа распознаёт паспорта, национальные ID-карты, водительские удостоверения и другие официальные документы. Перечень регулярно расширяется. Какие страны и типы документов принимаются на конкретном шаге, задаётся в сценарии: при настройке шага вы выбираете нужные страны и типы документов. Если нужного документа нет в списке, напишите в поддержку.

Если нужный документ пока не поддерживается, обратитесь в поддержку NeuroVision. Команда оценит, можно ли его добавить, и сообщит сроки. Добавление нового типа документа требует времени на подготовку, поэтому запрос лучше отправить заранее.

• Документ должен целиком помещаться в кадр, а все важные зоны — фотография, печати, номера, машиночитаемая зона — быть видны полностью.
• Не используйте вспышку: она даёт блики на ламинате.
• Не закрывайте документ пальцами.
• Для селфи смотрите прямо в камеру при достаточном освещении, лицо должно быть открыто и целиком в кадре.
• Не используйте фильтры и не обрабатывайте снимки в редакторе.

По умолчанию платформа рассчитана на фотографии оригинальных документов. Если в сценарии включены антифрод-проверки, копии и распечатки отклоняются с кодами [fraud] image printed, [general] black and white image или [fraud] image edited. Эти проверки можно отключить в редакторе сценариев. Тогда качественные сканы и копии принимаются, если они соответствуют остальным требованиям: разрешению, полноте документа и видимости полей.

Распознавание документа, антифрод-проверки и сравнение лиц выполняются за секунды. Если в сценарии есть Liveness, общее время зависит от пользователя: выполнение заданий перед камерой занимает от нескольких секунд до минуты, в зависимости от освещения и скорости реакции. В демо-режиме проверка может идти дольше, чем в рабочем окружении.

Проверка лица, особенно Liveness, проходит только через камеру: система должна убедиться, что перед ней живой человек, а не изображение. В веб-виджете документ снимается камерой, загрузки файлов в нём нет. Готовое изображение документа можно отправить на шаг сценария через REST API — это делает ваш сервер, а не виджет. Для лучшей защиты от подделок рекомендуем снимать документ камерой через веб-виджет.

Система принимает изображения только в форматах JPEG и PNG. Файлы других форматов (HEIC, WEBP, PDF и т. д.) отклоняются с кодом [general] bad image.

Требования к размеру относятся не только к файлу, но и к объекту на изображении. Если изображение слишком маленькое, вернётся [general] too small image; если документ занимает слишком малую часть кадра — [document] too small image. Лицо в селфи и фотография в документе должны быть хорошо видны.

Избегайте сильного сжатия, размытия и плохого освещения: они снижают качество распознавания и сравнения лиц.

Достаточно передать фотографию: система сама определит, какой документ на ней. Сценарий при этом задаёт, какие документы допустимы на шаге. Если распознанный документ не входит в этот список, вернётся код [document] bad document type.

Чаще всего неверное распознавание вызвано качеством снимка: бликами, размытием, недостаточным освещением. Новая фотография в хорошем качестве обычно решает проблему. Если ошибка повторяется на чётком снимке, напишите в поддержку и укажите идентификатор сессии.

Платформа проверяет наличие обязательных элементов документа (фотографии владельца, печати, подписи, полей), логику данных и признаки подделки: копию, распечатку, снимок с экрана, редактирование изображения. Проверить голограммы или UV-метки по обычной фотографии нельзя, поэтому такие признаки не анализируются.

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

Система извлекает поля документа (ФИО, дату рождения, номер документа и др.) независимо от языка, если сам документ входит в список поддерживаемых.

Liveness подтверждает, что перед камерой находится живой человек, а не фотография, видео или маска. Пользователь выполняет задания, которые показывает виджет. Режим проверки задаётся в сценарии:

• простые задания — отдельные команды: повернуть голову влево или вправо, посмотреть в указанную точку;
• сложные задания — комбинации действий в быстрой последовательности;
• круговое движение головы — пользователь медленно поворачивает голову по кругу.

По итогам выполнения заданий система выносит решение о прохождении проверки.

Чаще всего проверка не проходит из-за плохого освещения или невыполненных действий. Попросите пользователя:

• перейти в хорошо освещённое место;
• смотреть прямо в камеру и не закрывать лицо;
• выполнять задания так, как подсказывает экран.

Число попыток ограничено. Если они исчерпаны, для новой проверки нужна новая сессия.

Сценарий может состоять только из шагов с документами. В этом случае не подтверждается, что документ предъявляет его владелец, и риск мошенничества выше. Отключать Liveness имеет смысл только в сценариях с низким риском.

Liveness отличает живое лицо от фотографии, записи на экране или маски. Если пользователь пытается показать камере экран с видео другого человека или надеть маску, проверка не засчитывается.

Антифрод-проверки платформы:

• признаки подделки документа: копия, распечатка, снимок с экрана, редактирование изображения, физические изменения документа;
• поиск того же лица в прошлых сессиях — чтобы выявить человека, который проходит проверку под разными данными;
• чёрный список лиц;
• контроль того, что в одной сессии используется один и тот же документ одного человека.

Какие проверки включены, задаётся в сценарии. Коды ошибок антифрода собраны в разделе [fraud] на странице Коды ошибок KYC.

Система определила, что на снимке, вероятно, не оригинал документа, а его копия или распечатка — чёрно-белая или цветная. Попросите пользователя сфотографировать оригинал документа.

При новой проверке система сравнивает лицо пользователя с лицами из прошлых сессий. Если лицо уже встречалось — с другим документом или другими данными, — это видно в личном кабинете: идентификатор сессии выделяется красным. По клику на него открывается список всех сессий, в которых встречалось это лицо.

Лицо из сессии можно добавить в чёрный список прямо в личном кабинете: в карточке сессии нажмите на значок с перечёркнутым кругом. При следующих попытках:

• если лицо совпадает с лицом из чёрного списка, сессия отклоняется с кодом [fraud] black list;
• в личном кабинете у такой сессии отображается пометка «Пользователь в чёрном списке».

Механизм опирается на лицо, а не на данные документа, поэтому срабатывает и при смене документа. Дополнительной разработки на вашей стороне не требуется.

В документации описаны методы REST API, форматы запросов и ответов, вебхуки и коды ошибок. Начните со страницы REST API; коды ошибок — на странице Коды ошибок KYC.

1. Запросите у менеджера NeuroVision код приглашения. 2. Зарегистрируйтесь с ним в личном кабинете. 3. В личном кабинете настройте сценарии проверки, вебхуки и интеграцию, а также следите за сессиями и статистикой.

Объёмы, лимиты и условия работы в рабочем окружении обсуждаются с менеджером.

1. Ваш сервер создаёт сессию проверки по выбранному сценарию. 2. Изображения документа и лица отправляются в сессию по шагам сценария. 3. Платформа проверяет каждое изображение и возвращает результат шага: распознанные данные или коды ошибок. 4. Итоговый результат сессии вы получаете вебхуком или запросом статуса сессии.

Если вы используете веб-виджет, шаги 2 и 3 он выполняет сам.

Сессия проходит шаги сценария по порядку: например, фотография документа, затем селфи с документом, затем Liveness. Через REST API каждое изображение отправляется на свой шаг, а результат шага приходит в ответе. Веб-виджет проводит пользователя по шагам сам и снимает кадры камерой, загрузки файлов в нём нет.

При создании сессии платформа присваивает ей уникальный идентификатор. По нему вы отправляете изображения в сессию, запрашиваете статус и результат, а также находите сессию в личном кабинете. Чтобы связать сессию с пользователем в вашей системе, используйте clientKey.

Сессия связана с одной попыткой проверки. Если пользователь не прошёл проверку и начинает заново или проверку проходит другой пользователь, создайте новую сессию. Завершённые и истёкшие сессии новых изображений не принимают.

• Вебхук. Укажите в настройках сценария URL вашего сервера. По умолчанию платформа отправляет на него уведомление с идентификатором сессии, статусом и данными при каждом изменении сессии. Чтобы получать только итоговый результат, включите флаг «Уведомлять только если сессия финализирована». Тело вебхука можно шифровать секретным ключом сценария — флаг «Зашифровать тело POST-запроса с помощью секретного ключа»; это тот же ключ, что и для clientKey.
• Запрос статуса. Метод /kyc/session/status возвращает текущий статус и результат сессии.

Проверки по внешним базам, не отмеченные в сценарии как блокирующие, на статус сессии не влияют: их результат приходит отдельно — методом kyc/session/databases и отдельным вебхуком о завершении проверок по базам. Если не пройдена проверка, отмеченная в сценарии как блокирующая, сессия после завершения проверок по базам переходит в статус failed с кодом [legal] database check failed — см. коды ошибок KYC.

На странице собраны все коды, которые возвращают методы /kyc/process и /kyc/session/status, по категориям. Для каждого кода указано, что он означает и что делать пользователю. Тексты из колонки «Что делать» можно показывать пользователю как подсказку.

Примеры:

• [general] bad image — файл не является изображением;
• [document] text fields not visible — поля документа не видны;
• [fraud] mobile device — в кадре экран мобильного устройства.

Если встретился код, которого нет в справочнике, напишите в поддержку.

Для каждого распознанного поля документа возвращаются:

• название поля (title) — например, фамилия, дата рождения, номер документа;
• значение (value);
• уровень уверенности распознавания (conf);
• признаки проблем с полем, например isUnreadable — поле не удалось прочитать.

Пример поля:

{
  "title": "Given name(s)",
  "value": "IVAN",
  "conf": "high"
}

Также в ответе могут быть строки машиночитаемой зоны (MRZ), даты в формате ISO, результаты антифрод-проверок и сравнения лиц.

Сессия считается непройденной, если не прошла хотя бы одна проверка сценария. Например, данные документа прочитаны, но:

• лицо на селфи не совпало с фотографией в документе;
• не пройдена проверка Liveness;
• найдены признаки подделки или съёмки с экрана;
• поле распознано с недостаточной уверенностью;
• срок действия документа истёк.

Конкретную причину показывают коды ошибок в ответе — см. Коды ошибок KYC.

Виджет проводит пользователя по всем шагам сценария: фотография документа, селфи, Liveness. Он подключается на страницу несколькими строками кода и сам отправляет данные на проверку, поэтому разрабатывать собственный интерфейс не нужно.

Подключите скрипт виджета на страницу и вызовите метод window.KYCWidget.setupKYC({...}), передав scenarioId вашего сценария и зашифрованный clientKey. Для React есть npm-пакет kyc-widget-nv с компонентом KycWidget: npm i kyc-widget-nv. Оба способа с примерами — на странице Подключение, порядок шифрования clientKey — на странице clientKey.

Веб-виджет работает в мобильных браузерах и внутри приложений через WebView. Он адаптирован под мобильные экраны и использует камеру смартфона. Что настроить в WebView на iOS и Android — на странице Мобильные приложения и WebView.

В настройках Web SDK сценария загружаются логотипы для светлой и тёмной темы, задаются фирменные цвета, тексты экранов, языки и цвет маски на проверке Liveness. Тему при запуске можно переопределить параметром theme. Подробнее — на странице Параметры.

В личном кабинете можно создать несколько сценариев KYC: например, только паспорт, паспорт и селфи, проверку с дополнительными документами. У каждого сценария свой идентификатор. При подключении виджета передайте scenarioId того сценария, который нужен для этой проверки.

Если сценарий связан в личном кабинете с другими сценариями, передавайте его идентификатор во всех запросах: сессия сама выберет сценарий группы по первому документу пользователя, а в ответах и вебхуках останется сценарий, который вы передали. Подробнее — вопрос «Что такое связанные сценарии и как сессия выбирает сценарий по первому документу?».

clientKey — строка до 36 символов, например идентификатор пользователя или заявки. Платформа его не выдаёт: значение придумываете вы. Для виджета значение шифруется на вашем сервере секретным ключом сценария, а в REST API передаётся в исходном виде. По clientKey можно найти все сессии пользователя и сопоставить вебхук с вашей заявкой. Подробно — на странице clientKey.

Статус	Что означает
idle	Сессия создана, пользователь ещё проходит шаги
processing	Изображения обрабатываются
success	Все проверки сценария пройдены
failed	Хотя бы одна проверка сценария не пройдена
exception	При обработке произошла внутренняя ошибка
expired	Время жизни сессии истекло до завершения проверки
suspicious	Найдены признаки мошенничества: лицо из чёрного списка, то же лицо с другими данными, разные документы в одной сессии

Итоговые статусы — success, failed, exception, expired и suspicious. Проверки по внешним базам на статус не влияют, если проверка не отмечена в сценарии как блокирующая; не пройденная блокирующая проверка переводит сессию в статус failed с кодом [legal] database check failed — см. коды ошибок KYC.

Сессия остаётся в статусе idle, пока пользователь проходит шаги: например, загрузил документ, но ещё не сделал селфи, или закрыл окно до завершения. Если время жизни сессии истекло, а шаги не пройдены, сессия получает статус expired.

Если проверка не пройдена, в ответе приходят коды ошибок, например:

{
  "errors": [
    "[fraud] mobile device",
    "[document] text fields not visible"
  ]
}

Здесь документ сфотографирован с экрана мобильного устройства, а часть полей документа не видна. Расшифровка каждого кода и что делать пользователю — на странице Коды ошибок KYC.

Система не нашла на изображении всех обязательных элементов документа, например защитных. Часто причина в том, что часть документа не попала в кадр или закрыта пальцами. Попросите пользователя сфотографировать документ целиком. Если элементов действительно нет, документ недействителен и нужен другой.

Возможные причины:

• файл не изображение, например PDF или DOCX;
• формат не поддерживается: принимаются только JPEG и PNG;
• файл пустой или повреждён.

Отправьте фотографию в формате JPEG или PNG.

Система сравнила лицо пользователя с фотографией в документе и не подтвердила, что это один человек. Причины:

• на селфи другой человек;
• плохое качество снимков: размытие, тени, неудачный ракурс, слабое освещение;
• сильные изменения внешности по сравнению с фотографией в документе.

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

Время жизни сессии задаётся в настройках сценария (у сессии связанных сценариев — сценария входа, с которым её начали). Если пользователь не прошёл все шаги за это время, сессия получает статус expired. Истёкшие сессии видны в личном кабинете. Чтобы пользователь прошёл проверку заново, создайте новую сессию.

Результаты сессии доступны через API по идентификатору сессии и в личном кабинете, там же их можно выгрузить в отчёт. Срок хранения данных уточните у менеджера. Ключевые поля удобно сохранять у себя для своих бизнес-процессов.

On-Premise версия устанавливается в IT-инфраструктуре клиента. Изображения и результаты обрабатываются и хранятся только на ваших серверах. Поддерживаются изолированные контуры без доступа в интернет. Установку и настройку выполняют специалисты NeuroVision совместно с вашей IT-службой.

Такой вариант подходит банкам, государственным и медицинским организациям и другим компаниям, которым важен полный контроль над данными.

	Облако	On-Premise
Где работает	Серверы NeuroVision	Ваши серверы
Данные	Хранятся на стороне NeuroVision	Не покидают вашу инфраструктуру
Обновления и поддержка	Выполняет NeuroVision	Совместно с вашей IT-службой
Возможности	Одинаковые	Одинаковые

Требования зависят от ожидаемого числа проверок и параллельных сессий. Для рабочих сред с высокими требованиями к доступности рекомендуется резервирование. Конкретную конфигурацию подберут специалисты NeuroVision.

1. NeuroVision сообщает о доступном обновлении и согласует время установки. 2. Специалисты устанавливают обновление по согласованному с вами защищённому каналу. 3. После установки проверяется работа ключевых функций.

Обработка изображений и хранение данных происходят внутри вашей сети, данные её не покидают. Доступ во внешнюю сеть может понадобиться только для установки обновлений; их можно проводить в контролируемом порядке.

По результатам успешной проверки KYC создаётся цифровой паспорт — подтверждённый профиль личности, записанный в распределённой сети. Его можно предъявлять в сервисах-партнёрах, не проходя идентификацию заново.

Цифровой паспорт подключается по согласованию с клиентами и партнёрами. Чтобы обсудить подключение, свяжитесь с командой NeuroVision.

• Для небольших объёмов — оплата за каждую проверку.
• Для крупных объёмов — пакеты с предоплаченным количеством проверок.

Стоимость и условия закрепляются в договоре.

Пакет проверок не привязан к месяцу или дню: например, пакет на 10 000 проверок можно израсходовать за день или распределить на год.

Когда средств на балансе недостаточно, проверка возвращает код [system] balance too low. После пополнения баланса повторите попытку. Чтобы избежать перерыва, следите за остатком баланса заранее.

В разделе «KYC Отчёты» можно:

• выбрать период;
• отфильтровать сессии по статусу, ошибкам и значениям полей;
• увидеть число найденных сессий;
• выгрузить отчёт.

По окончании отчётного периода NeuroVision готовит закрывающие документы с количеством проведённых проверок и передаёт их вам на подписание.

Многие клиенты сначала проводят пилот, а затем заключают долгосрочный договор на больший объём. Как правило, стоимость одной проверки в крупном пакете ниже. Условия согласуйте с менеджером NeuroVision.

Режим работы поддержки и каналы связи закрепляются в договоре; круглосуточная поддержка подключается отдельно. Чтобы ускорить ответ, укажите в обращении идентификатор сессии и название сценария.

Сценарии настраиваются в редакторе сценариев личного кабинета без участия разработчиков. В сценарии можно задать:

• шаги проверки и их порядок — например, документ, затем селфи с документом;
• страны и типы документов для каждого шага;
• проверки на шаге: машиночитаемая зона, признаки редактирования, съёмка с экрана, копии и распечатки, сравнение лиц и другие;
• время жизни сессии;
• допустимое число критических ошибок;
• возрастные ограничения;
• антифрод-правила: например, отклонять сессию, если в ней использованы разные документы.

Вебхуки для уведомлений вашего сервера настраиваются там же, в личном кабинете.

Сценарии можно связать между собой: тогда сессия выбирает сценарий группы по первому документу пользователя и дальше идёт по шагам выбранного сценария (см. следующий вопрос). Сценарий, связанный с другими, сохраняется, только если правка не нарушает правила связывания.

Связанные сценарии удобны, когда под разные документы нужны разные проверки: например, один сценарий — для внутреннего паспорта с проверками по базам, другой — для заграничных паспортов и ID-карт. Сценарии связывают в редакторе сценариев личного кабинета, а во всех запросах передают идентификатор одного сценария — сценария входа.

Как выбирается сценарий:

• на первом шаге сессия принимает документы первых шагов всех связанных сценариев; в виджете панель «Какие документы подходят для верификации?» перечисляет документы и страны каждого сценария;
• сценарий выбирает лицевая сторона документа, подошедшая первому шагу одного из сценариев; оборотная сторона, прописка и селфи сценарий не выбирают;
• выбор окончательный: дальше сессия идёт по шагам и проверкам выбранного сценария, а виджет показывает экран успеха и сразу продолжает шагами выбранного сценария;
• документ, не подошедший ни одному сценарию, получает отказ, и пользователь переснимает его; попытки первого шага до выбора общие для сессии.

Что видит интегратор:

• <code>schemaId</code> в ответах API и вебхуках — всегда сценарий входа; <code>selectedSchemaId</code> — <code>null</code> до выбора, затем выбранный сценарий;
• <code>results</code> до выбора содержит одну задачу — первый шаг, после выбора — задачи выбранного сценария;
• до выбора номер шага <code>stepIndex</code> 1 и больше отклоняется ошибкой <code>[request] invalid stepIndex: out of range</code>, поэтому первый документ отправляйте без номера шага или с номером 0;
• вебхуки приходят на адрес сценария входа, а их шифрование и секретный ключ берутся из настроек сценария входа; этим же ключом шифруется <code>clientKey</code>; оформление и тексты виджета — тоже от сценария входа, а шаги и проверки — от выбранного сценария;
• фильтр сессий по <code>schemaId</code> в API находит сессию по сценарию входа.

Какие сценарии можно связать:

• в первом шаге — только лицевые стороны паспортов (кроме паспорта транспортного средства) или ID-карт, без анкеты в сценарии;
• первые шаги сценариев группы не пересекаются по типу документа и стране;
• настройки распознавания у всех сценариев группы одинаковы.

Сценарии сессии фиксируются при её создании: связи, изменённые позже, начатые сессии не меняют. Подробнее — в инструкции «Связанные сценарии» и в методе API «Создать новую KYC-сессию» (раздел «Сессия связанных сценариев»).

Работа облачной платформы отслеживается автоматически, и инженеры начинают устранять сбой, не дожидаясь обращений. Если вы заметили замедление или недоступность, сообщите в поддержку: укажите время, метод и идентификатор сессии. Для On-Premise версии диагностика проводится совместно с вашей IT-службой.