Что делает GOXOST KYC
Пользователь фотографирует документ, удостоверяющий личность, и делает короткое селфи. Затем GOXOST KYC:
- считывает данные документа и проверяет его подлинность, действительность и срок действия;
- проверяет, что в проверке участвует реальный человек (проверка присутствия);
- сравнивает селфи с фотографией в документе (сверка селфи с документом);
- по желанию проверяет имя по санкционным спискам (OFAC SDN, ООН, Великобритания, ЕС) и ищет дубликаты документов в вашем аккаунте.
Каждая проверка заканчивается одним решением:
| Решение | Значение | Что делаете вы |
|---|---|---|
GREEN |
Все проверки пройдены | Пропускаете пользователя |
RED |
Одна из проверок не пройдена. decision_type говорит, может ли пользователь попробовать снова (retry) или нет (final) |
Объясняете причину и, если можно, предлагаете повторить |
ON_HOLD |
Результат пограничный, решение должен принять человек | Ждёте ручной проверки в панели или решаете через API |
RED и ON_HOLD всегда приходят с машиночитаемыми reject_labels, например DOC_EXPIRED или FACE_MISMATCH. Полный список — в главе Процесс проверки.
Как работает интеграция
- Ваш бэкенд создаёт заявителя — проверяемого человека, привязанного к ID пользователя у вас (
external_id). - Ваш бэкенд создаёт сессию для этого заявителя и получает одноразовые
urlиtoken. - Пользователь проходит сценарий — вы отправляете его по
url(hosted-страница) или запускаете веб-виджет (kyc.js) либо Flutter SDK сtoken. - GOXOST KYC отправляет вебхук (
verification.completedилиverification.on_hold) на ваш бэкенд. - Ваш бэкенд читает решение через
GET /verifications/{id}и обновляет пользователя.
Your backend ──POST /applicants──────────────▶ GOXOST KYC → apl_…
Your backend ──POST /applicants/{id}/sessions▶ GOXOST KYC → { url, token }
User ──opens url / SDK with token────▶ hosted flow (document + selfie)
GOXOST KYC ──webhook verification.completed▶ Your backend
Your backend ──GET /verifications/{id}────────▶ GOXOST KYC → decision, checks, document data
Результат в браузере или приложении нужен только для пользовательского опыта — сообщение в браузере можно подделать. Итоговое решение всегда принимайте на бэкенде по вебхуку или по GET /verifications/{id}.
Секретный API-ключ остаётся на вашем сервере. Браузер или приложение получают только короткоживущие url или token сессии.
Варианты интеграции
Все варианты используют один и тот же бэкенд-API и одни и те же вебхуки; они различаются только тем, где пользователь проходит сценарий.
| Вариант | Когда подходит | Что вы делаете | Глава |
|---|---|---|---|
| Hosted-ссылка | Самый быстрый старт; ссылка в письме, SMS, чате или QR-коде | Только вызовы с бэкенда. Перенаправляете пользователя на url |
Процесс проверки |
Веб-виджет (kyc.js) |
Пользователь остаётся на вашем сайте | Один контейнер и один тег script | Web SDK |
| Flutter SDK | Приложения для Android и iOS; поддерживает электронную проверку документа | Один вызов KycFlow.start |
Flutter |
| Плагин WordPress | Сайты на WordPress | Устанавливаете и настраиваете плагин | WordPress |
| Direct API | Собственный интерфейс съёмки или серверная проверка уже имеющихся изображений | Всё: съёмка, UX, логика решения | Direct API |
Direct API не хранит состояние: он проверяет присланные изображения и возвращает результат в ответе. Он не создаёт заявителей, ничего не сохраняет и не отправляет вебхуки.
Окружения
| Тестовый | Боевой | |
|---|---|---|
| API-ключ | sk_test_… |
sk_live_… |
| Проверки | Имитация — результат выбираете вы | Реальные проверки документа, селфи и присутствия |
| Месячный лимит | Не ограничен (но учитывается) | Лимит вашего тарифа |
| Доступно | Сразу после регистрации | После верификации бизнеса |
Оба окружения используют один базовый URL; окружение определяет ключ. Данные между ними не пересекаются: тестовый ключ не видит боевых заявителей, а один и тот же external_id в тестовом и боевом режимах — это два разных заявителя. Подробнее — Тестовый и боевой режимы.
Базовый URL и соглашения
https://kyc.goxost.net/api/v1
- JSON поверх HTTPS, UTF-8. Время — ISO 8601 в UTC (
2026-11-09T10:00:00Z). Баллы — числа от0до1. - Каждый запрос аутентифицируется заголовком
Authorization: Bearer sk_test_…илиsk_live_…— см. Аутентификация. - У ID есть префикс типа:
apl_заявитель,ses_сессия,ver_проверка,whk_вебхук,whd_доставка вебхука,evt_событие. - В каждом ответе есть заголовок
X-Request-Id: req_…. Указывайте его при обращении в поддержку.
Что читать дальше
- Быстрый старт — первая проверка в тестовом режиме за пять шагов.
- Аутентификация — API-ключи, токены сессий и идемпотентность.
- Процесс проверки — заявители, сессии, решения и ручная проверка.
- Вебхуки — события, подписи и повторные отправки.
- Ошибки — коды ошибок, лимиты запросов и безопасные повторы.
- Справочник API — все эндпоинты и поля. Исходная схема — /docs/openapi.yaml, коллекция Postman — /docs/postman.json.