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

Интеграция · Глава 5

Процесс проверки

Как связаны заявители, сессии и проверки, что видит пользователь и как обрабатывать каждое решение.

8 мин чтения

Заявители

Заявитель — это проверяемый человек. Создавайте по одному на пользователя через POST /applicants и храните его id рядом с пользователем.

Поле Примечание
external_id Обязательное. ID пользователя у вас: до 100 печатных ASCII-символов, уникален в пределах окружения (повтор возвращает 409 conflict)
flow Ключ сценария, по умолчанию basic-kyc. Неизвестный ключ возвращает 422 unprocessable
locale uz, ru или en (по умолчанию uz). Язык hosted-сценария
purpose Необязательное, до 200 символов. Цель проверки по умолчанию для сессий этого заявителя; отображается в справке
metadata Необязательное. До 20 строковых ключей со строковыми значениями (до 200 символов каждое). Без персональных данных

email и phone пока не принимаются: непустое значение возвращает 400 validation_failed.

status заявителя — одно из значений:

status Значение
init Новый, после сброса или после RED с decision_type: retry. Можно создать сессию
on_hold Последняя проверка ждёт ручного рассмотрения
completed Есть окончательное решение (GREEN или RED с final)

У заявителя также есть последние decision, risk_score, last_verification_id и valid_until. Искать заявителей можно через GET /applicants (фильтры: external_id, status, decision, flow, created_from, created_to; курсорная пагинация). История попыток — в GET /applicants/{id}/verifications.

Сессии

Сессия — это одна попытка. Создайте её через POST /applicants/{id}/sessions:

{
  "redirect_url": "https://shop.example/kyc/done",
  "expires_in": 1800,
  "locale": "en",
  "purpose": "Account opening"
}
Поле Примечание
redirect_url Необязательное, только https://. После результата hosted-страница показывает кнопку «Вернуться в сервис» на этот адрес (в веб-виджете не показывается)
expires_in 60–1800 секунд, по умолчанию 1800
locale По умолчанию — язык заявителя
purpose Необязательное. По умолчанию — цель заявителя, затем цель по умолчанию из профиля бизнеса
contract Необязательное. { "sha256": "<64 hex>", "reference": "DOG-2026/17" } связывает проверку с вашим договором с клиентом. Передаётся и хранится только хеш; он отображается в справке

В ответе есть url (hosted-сценарий, короткая ссылка вида https://kyc.goxost.net/v/Xk7mQ2pL9aR4wTb8), token (для kyc.js и Flutter SDK) и expires_at.

Правила:

  • Сессию можно создать, только когда заявитель в статусе init; иначе 409 conflict — сначала сбросьте заявителя.
  • У заявителя одна активная сессия. Создание новой завершает предыдущую.
  • Сессия одноразовая. После отправки, истечения или отказа её ссылка возвращает 410, а SDK показывают ошибку; для новой попытки создайте новую сессию.
  • Язык hosted-страницы берётся из ?lang= в URL, затем из locale сессии, затем из языка браузера.
  • В боевом режиме создание сессии резервирует одну единицу месячного лимита (429 plan_limit_reached, когда он исчерпан). Неиспользованный резерв возвращается, если сессия истекла до отправки или была заменена.

Отслеживайте сессию через GET /sessions/{id}: status — created, started, submitted, processed, expired или abandoned, а steps_done перечисляет пройденные шаги.

Что видит пользователь

  1. Переход на телефон (только на компьютере). На компьютере без сенсорного экрана сценарий сначала предлагает QR-код, чтобы продолжить на телефоне. Окно на компьютере следит за телефоном и тоже показывает результат.
  2. Согласие. Пользователь соглашается на обработку своих данных, включая биометрические данные для селфи. Время согласия записывается в справку.
  3. Документ. Пользователь фотографирует документ — страницу паспорта с фотографией или лицевую и оборотную стороны ID-карты. Если снимок не подходит, пользователь сразу видит подсказку и может переснять.
  4. Селфи. Пользователь делает короткое селфи, следуя подсказкам на экране. Этот шаг также подтверждает, что в проверке участвует реальный человек.
  5. Обработка и результат. Выполняются проверки, и пользователь видит итог. Запоздавший результат показывается как «на рассмотрении».

Hosted-страница, веб-виджет и Flutter SDK показывают одни и те же шаги, внизу — значок «Powered by». Если в сценарии включена электронная проверка документа, Flutter SDK выполняет её после фото.

Вебхук session.started приходит, когда пользователь дал согласие, а verification.submitted — когда все шаги пройдены.

Решения

Когда проверки завершены, создаётся проверка (ver_…) и вы получаете verification.completed (GREEN или RED) или verification.on_hold. Полный результат читайте через GET /verifications/{id}.

decision decision_type status заявителя после Что делать
GREEN null completed Отметить пользователя как проверенного
RED retry init Сообщить пользователю, что пошло не так, и создать новую сессию
RED final completed Не подтверждать; для новой попытки нужен сброс
ON_HOLD null on_hold Ждать verification.reviewed

В результате также есть:

  • reject_labels — почему RED или ON_HOLD (таблица ниже);
  • checks — по одной записи на проверку (document, face_match, liveness, а если включены — aml, duplicate, age, а также doc_fraud и chip), в каждой status (pass, warn, fail или error), score и labels;
  • document — тип, страна и данные документа (document.data);
  • risk_score от 0 до 1;
  • valid_until — результат GREEN действует 2 года. За 30 дней до окончания и в момент окончания приходит applicant.reverification_due.
Важно

Решение принимайте только на бэкенде. Результат в колбэках kyc.js или во Flutter SDK нужен для пользовательского опыта — читайте решение из вебхука или GET /verifications/{id}.

stale: true отмечает результат, пришедший после сброса или удаления заявителя либо после открытия более новой сессии. Он остаётся в истории, но не меняет заявителя и не отправляет вебхук.

Причины отказа

Метка Тип Значение
BAD_QUALITY retry Снимок недостаточного качества — переснимите
DOC_NOT_SUPPORTED retry Тип документа или страна не разрешены в сценарии
MRZ_NOT_READABLE retry Данные документа не удалось считать — переснимите
MRZ_INVALID final Данные документа некорректны
MRZ_LOW_CONFIDENCE review Данные документа считаны, но недостаточно уверенно
DOC_DATA_MISMATCH final Данные документа не согласуются между собой, либо загруженные стороны от разных документов
DOC_EXPIRED retry Срок действия документа истёк
DOC_RECAPTURE retry Изображение документа не прошло проверку подлинности — переснимите оригинал документа. По умолчанию выключено
DOC_SCREEN_RECAPTURE review Изображение документа не прошло проверку подлинности
DOC_PRINTED_COPY review Документ, возможно, не является оригиналом
DOC_PHOTO_TAMPERED review Фото в документе не прошло проверку подлинности
DOC_TEMPLATE_MISMATCH review Документ, возможно, был изменён
DOC_FORGED final Признаки подделки
DOC_REVIEW_REQUIRED review Тип документа, который всегда проверяет человек
DOC_FACE_UNBOUND review Не удалось подтвердить, что стороны относятся к одному документу
PERSONAL_NUMBER_INVALID review Национальный персональный номер некорректен или не совпадает с другими данными документа
UNDERAGE final Младше минимального возраста сценария
AGE_UNKNOWN review Сценарий «только возраст»: не удалось прочитать дату рождения
FACE_NOT_FOUND retry На селфи или в документе не найдено лицо
FACE_MISMATCH final На селфи и на фото в документе разные люди
FACE_MATCH_UNCERTAIN review Сверка селфи с документом не дала однозначного результата
LIVENESS_FAILED retry Шаг селфи не завершён или время вышло
LIVENESS_UNCERTAIN review Проверка присутствия не дала однозначного результата
LIVENESS_SPOOF final Проверка присутствия не пройдена: реальный человек не участвовал
SANCTIONS_MATCH final Найден в санкционном списке: очень близкое имя и точная дата рождения
SANCTIONS_POSSIBLE review Возможное совпадение с санкционным списком (близкое имя, дата рождения в диапазоне или неизвестна)
PEP_MATCH review Публичное должностное лицо (PEP)
AML_NO_NAME review AML включён, но имя из документа прочитать не удалось
DUPLICATE final Этот номер документа уже использован другим заявителем в вашем аккаунте
CHIP_HASH_MISMATCH final Электронная проверка документа не пройдена
CHIP_SIGNATURE_INVALID final Электронная проверка документа не пройдена
CHIP_MRZ_MISMATCH final Электронные данные не совпадают со сфотографированным документом
CHIP_CHAIN_UNVERIFIED review Электронную проверку документа не удалось завершить для страны выдачи
CHIP_CLONE_SUSPECTED review Электронная проверка документа не дала однозначного результата
CHIP_NOT_READ review Сценарий требует электронную проверку документа, но она не выполнена
CHECK_UNAVAILABLE review Одна из проверок не выполнилась (сервис был недоступен)
REVIEW_EXPIRED retry Результат ON_HOLD не рассмотрен вовремя и отменён системой
MAX_ATTEMPTS final Попытки исчерпаны

Метки типа retry приходят с RED + retry, final — с RED + final, а review приводят к ON_HOLD. Могут появиться новые метки: неизвестную метку обрабатывайте как ON_HOLD и показывайте общее сообщение.

Ручная проверка

ON_HOLD означает, что решение должен принять человек. Рассмотреть можно:

  • в панели — откройте очередь проверки, посмотрите изображения документа и лица и примите решение; или
  • через API — POST /verifications/{id}/review:
{ "decision": "GREEN", "comment": "manual check ok" }
{ "decision": "RED", "decision_type": "final", "reject_labels": ["DOC_FORGED"] }
  • Рассмотреть можно только последнюю проверку заявителя в статусе ON_HOLD. Уже решённая, устаревшая или stale проверка возвращает 409 conflict; так же и проверка, которую в панели открыл другой проверяющий.
  • Для RED нужны decision_type и хотя бы одна метка. REVIEW_EXPIRED выбрать нельзя.
  • comment не сохраняется.
  • После рассмотрения приходит verification.reviewed с новым решением.
  • Если в аккаунте включено правило четырёх глаз (панель → Настройки → Проверка), RED через API возвращает 202 Accepted и остаётся ON_HOLD, пока другой человек не подтвердит его в панели. На GREEN это не влияет.

У каждого результата ON_HOLD есть review_deadline_at — 7 дней после решения. verification.review_reminder приходит сразу, затем за 2 дня и за 24 часа до срока. Если никто не решил вовремя, проверка становится RED + retry с REVIEW_EXPIRED, и вы получаете verification.reviewed.

Сброс и повтор

  • После RED + retry заявитель автоматически возвращается в init. Создайте новую сессию и снова проведите пользователя через сценарий.
  • Чтобы проверить заново после GREEN, RED + final или зависшей попытки, вызовите POST /applicants/{id}/reset. Статус становится init, decision, risk_score и last_verification_id очищаются, открытые сессии становятся abandoned. История остаётся в GET /applicants/{id}/verifications. Приходит applicant.reset.
  • Внутри одной сессии число попыток ограничено (20 загрузок документа, 10 попыток селфи, 5 загрузок селфи). Когда они закончатся, создайте новую сессию.
  • Чтобы удалить заявителя и его данные, вызовите DELETE /applicants/{id}. Он возвращает 202 с deletion_scheduled, отправляет applicant.deleted, после чего заявитель возвращает 404.

Сценарии

Сценарий (flow) — это настройка проверки: какие шаги и проверки выполняются и какие документы принимаются. В каждом аккаунте есть сценарий basic-kyc; другой ключ сценария передавайте в flow при создании заявителя.

Редактируйте сценарии в панели (Настройки): проверки (aml, duplicate, age_only), электронную проверку документа (off, optional, required, только мобильный SDK) и срок хранения данных. Каждое изменение создаёт новую версию сценария. Сессия использует версию, действовавшую при её создании, поэтому изменения никогда не затрагивают уже идущие сессии.

Правила принятия решений, минимальный возраст и список принимаемых типов документов и стран GOXOST KYC задаёт для всех аккаунтов; изменить их для отдельного аккаунта нельзя.

Читайте сценарии через GET /flows и GET /flows/{key}. Какие документы поддерживаются в какой стране — в публичном GET /documents/catalog.