Интеграция KYB: архитектура и паттерны

Это руководство дополняет краткое руководство. В нём описаны архитектура, все решения по интеграции и операционные практики, которые обеспечивают надёжную работу KYB в продакшене.

Архитектура

Аутентификация

Все запросы требуют заголовка x-api-key с API-ключом вашего приложения. См. аутентификация API: там описаны ротация ключей, разделение сред и области доступа.

Создание сессии

Единственный эндпоинт: POST /v3/session/. Тип сценария определяет, является сессия KYC или KYB, поэтому отдельный флаг «business» не нужен. Рекомендуемые поля при создании:

Поле	Назначение
`workflow_id`	Обязательно. Ссылается на ваш сценарий KYB.
`vendor_data`	Ваш идентификатор бизнеса. Привязывает сессию к сущности Business.
`callback_url`	Необязательно. Куда перенаправить пользователя после завершения.
`expected_details`	Необязательно. `{ company_name, registry_country, registration_number }`. Предзаполняет поиск в реестре компаний: страна регистрации выбирается заранее и фиксируется (`registry_country` в формате `XX` или `XX-YY` для реестров на уровне штатов, например `US-CA`), поля названия компании и регистрационного номера заполняются, а проверочный поиск запускается автоматически, используя оба идентификатора, если они указаны. Только предзаполнение: несоответствия не формируют предупреждений.
`metadata`	Необязательно. JSON, прикрепляемый к сессии.

Полная схема: создание сессии.

Передача размещённой ссылки

url в ответе — это размещённая ссылка на верификацию. Варианты передачи:

Отправить её по электронной почте со своей платформы.
Встроить её в ваш интерфейс онбординга в виде ссылки.
Открыть во встроенном webview в приложении (iOS / Android / React Native).

Вы можете настроить размещённый интерфейс (логотип, цвет, домен, шаблоны писем) через White label.

Опрос и webhook

Рекомендуемый способ — webhook. Didit отправляет события о завершении методом POST на ваш эндпоинт, указанный для подписки, сразу после окончания обработки. Опрос поддерживается для разработки или когда ваш эндпоинт webhook недоступен:

Опрашивайте GET /v3/session/{id}/decision/ с экспоненциальной задержкой (сначала каждые 10 с, постепенно увеличивая интервал до 60 с).
Прекращайте опрос, когда status принимает одно из значений "Approved", "Declined", "In Review".

Частый опрос может привести к превышению лимитов запросов. В продакшене всегда отдавайте предпочтение webhook.

Обработка webhook

Подпишитесь на события, которые вам нужны. Одни и те же события относятся и к KYC, и к KYB, а признаком событий бизнес-сессий служит session_kind: "business" в теле события:

status.updated: статус сессии изменился. Для сессий KYB фильтруйте по session_kind === "business".
data.updated: проверяющий отредактировал данные реестра или ключевых лиц в консоли либо реестр сообщил об изменении. Это событие не отправляется, когда заявитель загружает документ или подаёт данные о ключевых лицах: для этого следите за status.updated. Тот же фильтр session_kind применяется и здесь.
business.status.updated / business.data.updated: связанная сущность Business изменилась.

Полный каталог событий: webhooks KYB. Проверка подписи и семантика повторных отправок: справочник по webhooks.

Обработка решений

switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}

Полную модель состояний см. в статусах KYB, а теги, которые объясняют решение, в предупреждениях KYB.

Повторная подача

Когда сессия верификации бизнеса (KYB) переходит в Resubmitted (или функция помечена для повторной подачи), бизнесу нужно загрузить исправленные или дополнительные данные. Вы можете:

Повторно передать тот же url: размещённый сценарий продолжит с шага, на котором требуется повторная подача.
Выпустить новую ссылку для ключевого лица, если сессия KYC физического лица была удалена или истекла до того, как это лицо её начало. Для этого используйте Regenerate Key People KYC Session: участник получит новую сессию.
Открыть кейс в Business Console, чтобы отслеживать внутреннюю переписку.

Выполнение шагов из вашего фронтенда

Шаги с документами и ключевыми лицами можно также выполнять с вашего сервера с помощью API-ключа. Так интерфейс остаётся за вами, а проверка и решение остаются за Didit. Каждый вызов относится к сессии KYB и требует разрешения write:businesses (для чтения извлечённых участников также подходят read:businesses или read:sessions). Он выполняет те же проверки, тарификацию и переход к следующему шагу, что и размещённая страница.

Загрузите корпоративные документы, пока сессия находится на шаге «KYB Documents».
Получите участников, названных в документах, включая акционеров и доли владения, и покажите их заявителю.
Создайте, измените и удалите черновики участников. Черновик не заявляется и ничего не стоит.
Отправьте черновики. Didit определяет, каких участников нужно проверить, создаёт сессию KYC для каждого и возвращает его kyc_session_url, который вы отправляете или встраиваете.
Получите итоговое решение из сессии, как и в случае размещённого сценария.

Если вызов сделан, пока сессия находится на другом шаге, API возвращает 409 kyb_step_mismatch с указанием текущего шага. Если сессия завершена, API возвращает 409 kyb_session_not_writable.

Агрегация профиля бизнеса

Если вы передаёте vendor_data при создании сессии, Didit объединяет все сессии этого бизнеса в одну сущность Business. Используйте словарь features сущности, чтобы узнать, полностью ли бизнес верифицирован прямо сейчас, без перебора сессий. Преимущества:

Периодические повторные процедуры KYB добавляются в тот же профиль.
Транзакции, которые мониторятся по тому же vendor_data, несут контекст риска бизнеса.
UBO и руководители, связанные с сущностями User, формируют связи между сущностями.

Практика	Зачем
Всегда передавайте `vendor_data`	Без него сессия остаётся без привязки, и её нельзя агрегировать.
Используйте webhook, а не опрос	Меньшая задержка и отсутствие риска упереться в лимит запросов.
Проверяйте подписи webhook	Защищает от подменённых событий.
Сохраняйте `session_id` на своей стороне	Нужен для получения решения и генерации PDF.
Помечайте сессии с помощью `metadata`	Упрощает отчётность и отладку.
Настройте тестовый сценарий	Используйте сценарий в песочнице для интеграционного тестирования перед переходом в продакшн.

Обработка ошибок

Ситуация	Ответ
Неверный `workflow_id`	`400 Bad Request`
Дублирующая сессия с тем же `vendor_data`	Создаётся новая сессия. Так задумано, поскольку повторная верификация предполагается.
Страна компании вне списка стран, разрешённых в сценарии	Проверка реестра выводит предупреждение `KYB_COUNTRY_RESTRICTED`.
Сбой у поставщика реестра при поиске компании	`POST /v3/kyb/search/` возвращает `502` с `code: "kyb_registry_provider_unavailable"`. Не тарифицируется. Повторите запрос или ориентируйтесь на `code`, чтобы предложить ручной ввод данных компании. В размещённом сценарии Didit компания автоматически перенаправляется на ручной ввод данных, а не получает ошибку, требующую только повторной попытки. См. Поиск в реестре KYB.
Лимит запросов	`429 Too Many Requests` с заголовком `Retry-After`.

Полный справочник по лимитам запросов.

Дальнейшие шаги

Webhook

Все события и payload KYB.

Статусы

Справочник по машине состояний.

Схема ответа

Расшифровка решения KYB.

Начало работы

Функции

Профили компаний

Справочник

Консоль

Интеграция KYB: архитектура и паттерны

Архитектура

Аутентификация

Создание сессии

Передача размещённой ссылки

Опрос и webhook

Обработка webhook

Обработка решений

Повторная подача

Выполнение шагов из вашего фронтенда

Агрегация профиля бизнеса

Рекомендации

Обработка ошибок

Дальнейшие шаги

Webhook

Статусы

Схема ответа

​Архитектура

​Аутентификация

​Создание сессии

​Передача размещённой ссылки

​Опрос и webhook

​Обработка webhook

​Обработка решений

​Повторная подача

​Выполнение шагов из вашего фронтенда

​Агрегация профиля бизнеса

​Рекомендации

​Обработка ошибок

​Дальнейшие шаги

Webhook

Статусы

Схема ответа

Архитектура

Аутентификация

Создание сессии

Передача размещённой ссылки

Опрос и webhook

Обработка webhook

Обработка решений

Повторная подача

Выполнение шагов из вашего фронтенда

Агрегация профиля бизнеса

Рекомендации

Обработка ошибок

Дальнейшие шаги