> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Продакшн-готовая интеграция KYB с Didit: архитектура, сессии, размещённые сценарии, webhooks и решения. От $2.00 за проверку, по стране и уровню.



Промпт интеграции KYB
        Скопировать промпт в буфер обмена



      
      

\<pre>

\````# Goal — ship a production-ready KYB (business verification) integration

KYB runs through the same `/v3/session/` endpoint as KYC. The session's workflow determines whether it's a KYC or KYB session — pass a KYB workflow id and Didit creates a business session automatically (`session_kind: "business"`).

\## End-to-end flow

\```
You: POST /v3/session/ (KYB workflow_id, vendor_data) → session_id, url, session_token
You: deliver url to the business contact (email / your UI / iframe)
Biz: completes the hosted flow (registry confirm → Key People → documents → AML)
Didit → Webhook: status.updated with session_kind: "business"
You: GET /v3/session/{session_id}/decision/ → full KYB decision
You: branch on decision.status ("Approved" / "Declined" / "In Review" / "Resubmitted")
\```

\## Create a KYB session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$KYB_WORKFLOW_ID",
"vendor_data": "biz-acme",
"callback": "https://myapp.com/kyb/return",
"metadata": {"plan": "growth", "country": "GBR"}
}'
\```

Recommended fields:

\- `workflow_id` — references your KYB workflow.
\- `vendor_data` — your business id; binds the session to a [Business entity](/entities/businesses/overview).
\- `callback` — where to redirect the user after completion.
\- `metadata` — JSON attached to the session for your own reporting.

\## Webhook events for KYB

\| Event | Trigger |
\|---|---|
\| `status.updated` (with `session_kind === "business"`) | KYB session status changed. Follow this event for progress. |
\| `data.updated` (with `session_kind === "business"`) | A reviewer edited registry data or Key People in the console, or the registry reported a change (registry monitoring). Not sent for document uploads or Key People submissions. |
\| `business.status.updated` | Linked Business entity status changed |
\| `business.data.updated` | Linked Business entity profile / counters changed |

Subscribe via `POST /v3/webhook/destinations/` with `webhook_version: "v3"`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON). De-dupe on `event_id`. Respond within 5 seconds.

\## KYB decision shape (V3 plural arrays)

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Key V3 arrays you'll iterate:

\| Array | Holds |
\|---|---|
\| `key_people_checks[]` | UBOs, shareholders, directors, officers — bucketed into `registry` (from the registry lookup) and `submitted` (what the business confirmed). Plus a `ubo_kyc_summary` rollup. |
\| `document_verifications[]` | Each item has `status`, `node_id`, `items[]` (signed `file_url` + OCR extract), `groups`, `required_groups`. |
\| `aml_screenings[]` | Company AML and per-person AML hits. |

The KYB-specific features are `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. Statuses are the exact labels `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"`.

\## Apply-decision logic

\```ts
switch (decision.status) {
case "Approved":   await onboardBusiness(decision); break;
case "Declined":   await logRejection(collectWarnings(decision), decision); break; // warnings[] tags on each feature array
case "In Review":  await markPending(decision); break; // wait for next webhook
case "Resubmitted":await notifyBusiness(decision); break; // business needs to re-upload
case "Awaiting User": await pingChildPersonForKyc(decision); break; // child Key People KYC pending
}
\```

See /business-verification/statuses for the full state machine.

\## Resubmission flow

When a session transitions to `Resubmitted` (or a feature to `Resub Requested`, or a feature is marked for resubmission), re-deliver the same `url` — the hosted flow resumes at the resubmission step. To re-verify a specific Key Person, resubmit that person's child KYC session; the parent `kyb_key_people` re-aggregates automatically.

\## Key People child KYC

If your KYB workflow has KYC required for some roles, each person triggers a child KYC session automatically. While any child is in progress, the parent's `kyb_key_people` status is `Awaiting User`. Configure per-role required/skippable behaviour at *Workflows → [KYB workflow] → Key People*. A child session expires after the session expiration time of the KYC workflow its role is mapped to, not the KYB session's. A party whose session was deleted, or whose link expired before the person started it, is reissued with `POST /v3/session/{session_id}/kyb/parties/{party_uuid}/regenerate/`.

\## Failure modes

\| Scenario | Response |
\|---|---|
\| Invalid `workflow_id` | `400 Bad Request` |
\| Wrong workflow type (KYC instead of KYB) | Session is created but runs KYC steps — verify the workflow's `workflow_type` is `"kyb"` |
\| Duplicate `vendor_data` | A new session is created — that's by design for re-KYB |
\| Company country outside the workflow's allowed countries | The registry check raises the `KYB_COUNTRY_RESTRICTED` warning |
\| Registry provider outage during company search | `502` with `code: "kyb_registry_provider_unavailable"`. Not billed. In Didit's hosted flow, the business is automatically offered manual company entry instead of a retry-only error. |
\| Rate limit | `429` with `Retry-After` header |

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /business-verification/response-schema — KYB decision payload
\- /business-verification/statuses — feature state machine
\- /business-verification/webhooks — KYB-specific event catalog
\- /entities/businesses/data-model — Business entity schema
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Вставьте в

Это руководство дополняет [краткое руководство](https://docs.didit.me/ru/business-verification/quickstart.md). В нём описаны архитектура, все решения по интеграции и операционные практики, которые обеспечивают надёжную работу KYB в продакшене.## Архитектура```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```## АутентификацияВсе запросы требуют заголовка `x-api-key` с API-ключом вашего приложения. См. [аутентификация API](https://docs.didit.me/ru/getting-started/api-authentication.md): там описаны ротация ключей, разделение сред и области доступа.## Создание сессииЕдинственный эндпоинт: `POST /v3/session/`. Тип сценария определяет, является сессия KYC или KYB, поэтому отдельный флаг «business» не нужен.**Рекомендуемые поля при создании:**| Поле | Назначение |
| - | - |
| `workflow_id` | Обязательно. Ссылается на ваш сценарий KYB. |
| `vendor_data` | Ваш идентификатор бизнеса. Привязывает сессию к [сущности Business](https://docs.didit.me/ru/entities/businesses/overview.md). |
| `callback_url` | Необязательно. Куда перенаправить пользователя после завершения. |
| `expected_details` | Необязательно. `{ company_name, registry_country, registration_number }`. Предзаполняет поиск в реестре компаний: страна регистрации выбирается заранее и фиксируется (`registry_country` в формате `XX` или `XX-YY` для реестров на уровне штатов, например `US-CA`), поля названия компании и регистрационного номера заполняются, а проверочный поиск запускается автоматически, используя оба идентификатора, если они указаны. Только предзаполнение: несоответствия не формируют предупреждений. |
| `metadata` | Необязательно. JSON, прикрепляемый к сессии. |Полная схема: [создание сессии](https://docs.didit.me/ru/sessions-api/create-session.md).## Передача размещённой ссылки`url` в ответе — это размещённая ссылка на верификацию. Варианты передачи:- Отправить её по электронной почте со своей платформы.
- Встроить её в ваш интерфейс онбординга в виде ссылки.
- Открыть во встроенном webview в приложении (iOS / Android / React Native).Вы можете **настроить** размещённый интерфейс (логотип, цвет, домен, шаблоны писем) через [White label](https://docs.didit.me/ru/console/white-label.md).## Опрос и webhookРекомендуемый способ — webhook. Didit отправляет события о завершении методом POST на ваш эндпоинт, указанный для подписки, сразу после окончания обработки.Опрос поддерживается для разработки или когда ваш эндпоинт webhook недоступен:* Опрашивайте `GET /v3/session/{id}/decision/` с экспоненциальной задержкой (сначала каждые 10 с, постепенно увеличивая интервал до 60 с).
* Прекращайте опрос, когда `status` принимает одно из значений `"Approved"`, `"Declined"`, `"In Review"`.> [!WARNING]
>
> Частый опрос может привести к превышению [лимитов запросов](https://docs.didit.me/ru/integration/rate-limiting.md). В продакшене всегда отдавайте предпочтение 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](https://docs.didit.me/ru/entities/businesses/overview.md) изменилась.Полный каталог событий: [webhooks KYB](https://docs.didit.me/ru/business-verification/webhooks.md). Проверка подписи и семантика повторных отправок: [справочник по webhooks](https://docs.didit.me/ru/integration/webhooks.md).## Обработка решений```typescript theme={null}
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](https://docs.didit.me/ru/business-verification/statuses.md), а теги, которые объясняют решение, в [предупреждениях KYB](https://docs.didit.me/ru/business-verification/warnings.md).## Повторная подачаКогда сессия верификации бизнеса (KYB) переходит в `Resubmitted` (или функция помечена для повторной подачи), бизнесу нужно загрузить исправленные или дополнительные данные.Вы можете:- **Повторно передать** тот же `url`: размещённый сценарий продолжит с шага, на котором требуется повторная подача.
- **Выпустить новую ссылку для ключевого лица**, если сессия KYC физического лица была удалена или истекла до того, как это лицо её начало. Для этого используйте [Regenerate Key People KYC Session](https://docs.didit.me/ru/sessions-api/regenerate-kyb-party.md): участник получит новую сессию.
- **Открыть [кейс](https://docs.didit.me/ru/transaction-monitoring/cases.md)** в Business Console, чтобы отслеживать внутреннюю переписку.## Выполнение шагов из вашего фронтендаШаги с документами и ключевыми лицами можно также выполнять с вашего сервера с помощью API-ключа. Так интерфейс остаётся за вами, а проверка и решение остаются за Didit.
Каждый вызов относится к сессии KYB и требует разрешения `write:businesses` (для чтения извлечённых участников также подходят `read:businesses` или `read:sessions`). Он выполняет те же проверки, тарификацию и переход к следующему шагу, что и размещённая страница.1) [Загрузите корпоративные документы](https://docs.didit.me/ru/sessions-api/kyb-upload-documents.md), пока сессия находится на шаге «KYB Documents».
2) [Получите участников, названных в документах](https://docs.didit.me/ru/sessions-api/kyb-extracted-parties.md), включая акционеров и доли владения, и покажите их заявителю.
3) [Создайте](https://docs.didit.me/ru/sessions-api/kyb-create-party-draft.md), [измените](https://docs.didit.me/ru/sessions-api/kyb-update-party-draft.md) и [удалите](https://docs.didit.me/ru/sessions-api/kyb-delete-party-draft.md) [черновики участников](https://docs.didit.me/ru/sessions-api/kyb-list-party-drafts.md). Черновик не заявляется и ничего не стоит.
4) [Отправьте черновики](https://docs.didit.me/ru/sessions-api/kyb-submit-parties.md). Didit определяет, каких участников нужно проверить, создаёт сессию KYC для каждого и возвращает его `kyc_session_url`, который вы отправляете или встраиваете.
5) Получите итоговое решение из сессии, как и в случае размещённого сценария.Если вызов сделан, пока сессия находится на другом шаге, API возвращает `409 kyb_step_mismatch` с указанием текущего шага. Если сессия завершена, API возвращает `409 kyb_session_not_writable`.## Агрегация профиля бизнесаЕсли вы передаёте `vendor_data` при создании сессии, Didit объединяет все сессии этого бизнеса в одну [сущность Business](https://docs.didit.me/ru/entities/businesses/overview.md). Используйте словарь `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](https://docs.didit.me/ru/standalone-apis/kyb-registry-search.md#обработка-сбоев-реестра). |
| Лимит запросов | `429 Too Many Requests` с заголовком `Retry-After`. |Полный справочник по [лимитам запросов](https://docs.didit.me/ru/integration/rate-limiting.md).## Дальнейшие шаги> [card] [Webhook](https://docs.didit.me/ru/business-verification/webhooks.md)
>
> Все события и payload KYB.> [card] [Статусы](https://docs.didit.me/ru/business-verification/statuses.md)
>
> Справочник по машине состояний.> [card] [Схема ответа](https://docs.didit.me/ru/business-verification/response-schema.md)
>
> Расшифровка решения KYB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.