Как это работает
- Ваш сервер создаёт заявителя и сессию (
POST /applicants/{id}/sessions) и передаёт на страницуtokenсессии. - Страница загружает
kyc.jsи вызываетKYC.init()с этим токеном. Проверка открывается в iframe внутри вашего контейнера. - Заявитель фотографирует документ и делает селфи. На компьютере без камеры проверка предлагает QR-код, чтобы продолжить на телефоне.
- В браузере срабатывает
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».