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

С чего начать · Глава 1

Обзор

GOXOST KYC проверяет, что ваш пользователь — реальный человек с подлинным документом, удостоверяющим личность, и сообщает вашему бэкенду, можно ли его пропустить.

3 мин чтения

Что делает GOXOST KYC

Пользователь фотографирует документ, удостоверяющий личность, и делает короткое селфи. Затем GOXOST KYC:

  • считывает данные документа и проверяет его подлинность, действительность и срок действия;
  • проверяет, что в проверке участвует реальный человек (проверка присутствия);
  • сравнивает селфи с фотографией в документе (сверка селфи с документом);
  • по желанию проверяет имя по санкционным спискам (OFAC SDN, ООН, Великобритания, ЕС) и ищет дубликаты документов в вашем аккаунте.

Каждая проверка заканчивается одним решением:

Решение Значение Что делаете вы
GREEN Все проверки пройдены Пропускаете пользователя
RED Одна из проверок не пройдена. decision_type говорит, может ли пользователь попробовать снова (retry) или нет (final) Объясняете причину и, если можно, предлагаете повторить
ON_HOLD Результат пограничный, решение должен принять человек Ждёте ручной проверки в панели или решаете через API

RED и ON_HOLD всегда приходят с машиночитаемыми reject_labels, например DOC_EXPIRED или FACE_MISMATCH. Полный список — в главе Процесс проверки.

Как работает интеграция

  1. Ваш бэкенд создаёт заявителя — проверяемого человека, привязанного к ID пользователя у вас (external_id).
  2. Ваш бэкенд создаёт сессию для этого заявителя и получает одноразовые url и token.
  3. Пользователь проходит сценарий — вы отправляете его по url (hosted-страница) или запускаете веб-виджет (kyc.js) либо Flutter SDK с token.
  4. GOXOST KYC отправляет вебхук (verification.completed или verification.on_hold) на ваш бэкенд.
  5. Ваш бэкенд читает решение через 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_…. Указывайте его при обращении в поддержку.

Что читать дальше

  1. Быстрый старт — первая проверка в тестовом режиме за пять шагов.
  2. Аутентификация — API-ключи, токены сессий и идемпотентность.
  3. Процесс проверки — заявители, сессии, решения и ручная проверка.
  4. Вебхуки — события, подписи и повторные отправки.
  5. Ошибки — коды ошибок, лимиты запросов и безопасные повторы.
  6. Справочник API — все эндпоинты и поля. Исходная схема — /docs/openapi.yaml, коллекция Postman — /docs/postman.json.

Содержание