Заявители
Заявитель — это проверяемый человек. Создавайте по одному на пользователя через 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 перечисляет пройденные шаги.
Что видит пользователь
- Переход на телефон (только на компьютере). На компьютере без сенсорного экрана сценарий сначала предлагает QR-код, чтобы продолжить на телефоне. Окно на компьютере следит за телефоном и тоже показывает результат.
- Согласие. Пользователь соглашается на обработку своих данных, включая биометрические данные для селфи. Время согласия записывается в справку.
- Документ. Пользователь фотографирует документ — страницу паспорта с фотографией или лицевую и оборотную стороны ID-карты. Если снимок не подходит, пользователь сразу видит подсказку и может переснять.
- Селфи. Пользователь делает короткое селфи, следуя подсказкам на экране. Этот шаг также подтверждает, что в проверке участвует реальный человек.
- Обработка и результат. Выполняются проверки, и пользователь видит итог. Запоздавший результат показывается как «на рассмотрении».
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.