OneKYC — документация

Настоящая документация предназначена для разработчиков, осуществляющих интеграцию с платформой OneKYC, а также для пользователей административной панели. Документация содержит описание продукта, руководство по интеграции и справочник API. Подробное описание возможностей платформы приведено в разделе О продукте.

Содержание документации:

• Введение — описание функциональных возможностей продукта и целевых сценариев использования.
• Быстрый старт — пошаговое руководство по созданию ссылки верификации и запуску первой KYC-сессии.
• Tenant API — описание программного интерфейса для серверной интеграции: Аутентификация, Сессии, Аппликанты, Документы и медиа, Ссылки верификации, Вебхуки, Метрики, Аудит, Справочник API (OpenAPI).
• KYB API — верификация юридических лиц: Обзор KYB, Быстрый старт, Справочник KYB API, KYB Вебхуки.
• Административная панель — управление дашбордом, сессиями, аппликантами, сценариями верификации (флоу), ревью, API-ключами, вебхуками, ссылками верификации, командой, аудитом и настройками.

Обратите внимание. Tenant API OneKYC находится в стадии бета-тестирования. Эндпоинты, форматы данных и версии API могут быть изменены. Рекомендуется отслеживать обновления документации.

Часто задаваемые вопросыCopy Anchor Link

Где выполняется верификация — на стороне клиента или на стороне OneKYC?Copy Anchor Link

Верификация выполняется на стороне OneKYC. Интеграция сводится к созданию ссылки верификации через API и её передаче конечному пользователю (по электронной почте, SMS, QR-коду и пр.). Пользователь переходит по ссылке на страницу верификации OneKYC, где проходит все предусмотренные сценарием проверки. Результаты передаются на сторону клиента посредством вебхуков или запросов к API.

Возможно ли встроить верификацию в собственный интерфейс?Copy Anchor Link

Да. Страницу верификации OneKYC можно открыть через редирект, в новом окне браузера или встроить через iframe. Пользовательский интерфейс OneKYC адаптивен и корректно работает как на настольных, так и на мобильных устройствах.

Чтобы встроить страницу верификации, передайте фрейму доступ к камере. Без атрибута allow браузеры блокируют камеру внутри iframe. В src укажите поле url из ответа на создание ссылки верификации:

<iframe
  src="<verification link url>"
  title="Проверка личности"
  allow="camera; microphone; fullscreen; clipboard-write"
  style="width: 100%; height: 100%; min-height: 680px; border: 0"
></iframe>

• Если ваша страница отдаёт заголовок Permissions-Policy, он должен разрешать камеру для домена верификации, например camera=(self "https://<verification domain>").
• Если на странице настроена Content Security Policy, добавьте домен верификации в frame-src.
• Рекомендуемый размер фрейма на десктопе — не меньше 600×680 px. На мобильных устройствах показывайте фрейм на весь экран или используйте редирект.
• После завершения проверки редирект заменяет всю страницу, а не только содержимое фрейма.
• Если доступ к камере во фрейме недоступен, пользователь может продолжить в новой вкладке или на телефоне по QR-коду.
• Встроенные браузеры приложений (Instagram, Facebook, TikTok) и нативные WebView могут ограничивать камеру; в нативных приложениях открывайте ссылку в системном браузере или выдайте WebView разрешение на камеру.

Как реализован cross-device flow?Copy Anchor Link

Пользователь может начать верификацию на настольном компьютере (для заполнения форм) и продолжить на мобильном устройстве (для съёмки документов и селфи). При создании ссылки генерируется QR-код; после сканирования пользователь продолжает ту же сессию на мобильном устройстве.

QR-код действителен в течение 5 минут и является одноразовым: после сканирования токен аннулируется. В случае истечения срока действия QR-кода необходимо обновить страницу для генерации нового кода.

Какие типы документов поддерживаются?Copy Anchor Link

Поддерживаются паспорта, идентификационные карты и водительские удостоверения большинства стран. Актуальный перечень доступен через Tenant API: GET /tenant/v1/kyc/documents/supported. В настройках флоу определяется, какие типы документов допустимы для конкретного сценария верификации.

Возможно ли настроить сценарий верификации?Copy Anchor Link

Да. Настройка сценариев осуществляется через Flow Editor в административной панели. Доступны следующие операции: добавление и удаление шагов (загрузка документа, селфи, liveness-проверка, OTP-подтверждение, AML-скрининг, ручное ревью), изменение порядка шагов и их параметров. Изменения применяются к новым сессиям после публикации обновлённой версии флоу.

Каким образом получать результаты верификации?Copy Anchor Link

Предусмотрены два способа:

1. Вебхуки (рекомендуемый способ) — OneKYC направляет уведомления о событиях на указанный URL в режиме реального времени (например, verification.approved, verification.declined).
2. Polling через API — периодический запрос статуса верификации через эндпоинт /tenant/v1/kyc/applicants/{applicant_id}/verification.

Какова длительность процедуры верификации?Copy Anchor Link

• Автоматическая верификация (без ручного ревью) — 30--60 секунд (загрузка документа, селфи, выполнение проверок).
• С ручным ревью — зависит от загрузки очереди операторов (от нескольких минут до нескольких часов).
• С AML-скринингом — дополнительно 5--15 секунд.

Какие действия предпринять, если пользователь не прошёл верификацию?Copy Anchor Link

Рекомендуемые действия зависят от причины отклонения (поле rejection_reason в ответе API):

• Низкое качество изображения — рекомендуется предложить пользователю повторить процедуру (создать новую ссылку верификации).
• Истёкший срок действия документа — рекомендуется уведомить пользователя о необходимости предоставить действующий документ.
• Несовпадение лица — возможный индикатор мошенничества; рекомендуется ручная проверка или отклонение.
• AML-совпадение — решение принимается на стороне клиента в соответствии с внутренними процедурами управления рисками.

Как тестировать интеграцию?Copy Anchor Link

1. Создайте API-ключ с префиксом kyc_test_ в административной панели.
2. Используйте тестовые ключи в среде разработки/staging.
3. Для тестирования вебхуков рекомендуется использовать ngrok или аналогичные инструменты для локальной разработки.
4. Сессии, созданные с тестовыми ключами, не учитываются в биллинге.

Возможно ли удаление данных пользователя (GDPR)?Copy Anchor Link

Да. Эндпоинт DELETE /tenant/v1/kyc/applicants/{applicant_id} создаёт запрос на удаление данных. Запрос проходит проверку перед исполнением; после подтверждения и выполнения удаление необратимо.

Как осуществляется тарификация?Copy Anchor Link

Тарификация производится на основании количества успешно завершённых верификаций. Тестовые ключи (kyc_test_*) не тарифицируются. Информация о тарифных планах доступна в административной панели или у персонального менеджера.

Для начала работы перейдите к разделу О продукте или Быстрый старт.