Перейти к содержимому
Справочник API Получить API-ключи

SDK и плагины · Глава 10

Web SDK

Встройте процесс проверки в свою веб-страницу с помощью kyc.js. Заявитель не покидает ваш сайт, а вы получаете события по ходу проверки.

3 мин чтения

Как это работает

  1. Ваш сервер создаёт заявителя и сессию (POST /applicants/{id}/sessions) и передаёт на страницу token сессии.
  2. Страница загружает kyc.js и вызывает KYC.init() с этим токеном. Проверка открывается в iframe внутри вашего контейнера.
  3. Заявитель фотографирует документ и делает селфи. На компьютере без камеры проверка предлагает QR-код, чтобы продолжить на телефоне.
  4. В браузере срабатывает onComplete, а ваш сервер получает вебхук с решением.
Важно

Секретный ключ остаётся на вашем сервере. Странице передаётся только token сессии — он действует для одной сессии и истекает вместе с ней.

Быстрый старт

Создайте сессию на сервере (см. Быстрый старт) и выведите её token на страницу:

<div id="kyc"></div>

<script src="https://kyc.goxost.net/sdk/kyc.js"></script>
<script>
  const flow = KYC.init({
    token: 'eyJ…',            // session token from your server
    container: '#kyc',
    locale: 'en',             // uz | ru | en
    onReady() {
      console.log('Flow loaded');
    },
    onComplete(result) {
      // UX only: show a "thank you" screen, then ask your server for the status
      showThankYou(result.decision);
    },
    onError(error) {
      if (error.code === 'session_expired' || error.code === 'link_invalid') {
        restartWithNewSession(); // ask your server for a new session
      }
    },
  });
</script>

Вызовите flow.destroy(), чтобы удалить iframe и перестать слушать события, — например, когда пользователь закрывает модальное окно или уходит со страницы в одностраничном приложении.

Параметры

KYC.init(options) возвращает { destroy() }.

Параметр Тип Описание
token string, обязательно token сессии из POST /applicants/{id}/sessions
container CSS-селектор или HTMLElement, обязательно Элемент, в который помещается iframe; его текущее содержимое заменяется
locale uz, ru, en Язык проверки. Если не задан: locale заявителя, затем язык браузера
onReady() function Проверка загрузилась
onComplete(result) function Заявитель завершил проверку. result — { decision, decision_type, reject_labels }
onError(error) function Проверка не может продолжаться. error — { code }
onEvent(event) function Все события ниже, включая ready, complete и error

KYC.init выбрасывает KYC: invalid token для пустого или некорректного токена и KYC: container not found, если селектор ничего не нашёл.

iframe занимает всю ширину контейнера. Его высота сначала 640 px, затем подстраивается под содержимое (не меньше 320 px), поэтому не задавайте контейнеру фиксированную высоту.

События

type Поля Когда
ready — Проверка загрузилась
step step: handoff, consent, document, liveness, processing Заявитель перешёл к новому шагу (handoff — экран «продолжить на телефоне»)
complete decision (GREEN, RED, ON_HOLD), decision_type (final, retry или null), reject_labels Результат готов
error code Проверка остановилась
resize height Изменилась высота содержимого (SDK сам меняет размер iframe)

Коды ошибок, которые нужно обработать:

code Значение Что делать
link_invalid Сессия неизвестна, использована или закрыта Создайте новую сессию
session_expired Сессия истекла во время проверки Создайте новую сессию
session_reset Заявителя сбросили, пока проверка была открыта Создайте новую сессию
network Проблема с соединением Попросите пользователя проверить соединение и повторить
unknown Любая другая ошибка Повторите; если ошибка повторяется, создайте новую сессию

Из проверки могут приходить и другие коды ошибок API — обрабатывайте незнакомые коды так же, как unknown.

Безопасность

  • onComplete — только для интерфейса. Сообщения из iframe можно подделать в браузере. Итоговое решение берите на сервере — из вебхука или из GET /verifications/{id}, — прежде чем что-либо открывать.
  • События содержат только коды и решение — никогда не имена, данные документа или изображения.
  • Если вы встраиваете iframe сами, без kyc.js, принимайте сообщение, только если event.origin равен https://kyc.goxost.net, event.source — contentWindow вашего iframe, а event.data.source — kyc-flow. kyc.js выполняет эти проверки за вас.

Content Security Policy и камера

Если ваш сайт отправляет Content Security Policy, разрешите GOXOST KYC:

Content-Security-Policy: script-src 'self' https://kyc.goxost.net; frame-src https://kyc.goxost.net

Если ваш сайт отправляет заголовок Permissions-Policy, он должен разрешать iframe доступ к камере:

Permissions-Policy: camera=(self "https://kyc.goxost.net")

Страница должна открываться по HTTPS — по обычному HTTP браузеры блокируют камеру. Сама страница проверки разрешает встраивание на любой сайт; её защищает токен сессии.

Hosted-ссылка вместо встраивания

Можно обойтись без kyc.js и отправить заявителя по url сессии (https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8) — редиректом, в новой вкладке, по SMS или по почте.

  • Укажите redirect_url (только HTTPS) при создании сессии: в конце проверки появится кнопка Вернуться в сервис, которая открывает этот адрес. Во встроенном режиме кнопка не показывается.
  • expires_in задаёт срок жизни ссылки: 60–1800 секунд, по умолчанию 1800.
  • У заявителя одна активная сессия. Создание новой закрывает предыдущую; закрытая ссылка возвращает 410, а страница сообщает пользователю, что ссылка больше не действует.
  • Редирект тоже не доказывает результат — читайте решение на сервере.

На каждой странице проверки есть небольшая отметка «Powered by GOXOST KYC».