> ## 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 集成指南：架构与模式（Didit）

> Didit 生产级 KYB 集成指南：涵盖架构、会话、托管流程、Webhook、轮询与决策。每次检查起价 $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/zh/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/zh/getting-started/api-authentication.md)。## 创建会话唯一的 endpoint 是 `POST /v3/session/`。会话是 KYC 还是 KYB 由工作流的类型决定，无需额外传入“企业”标志。**创建时建议填写的字段：**| 字段 | 用途 |
| - | - |
| `workflow_id` | 必填，引用你的 KYB 工作流。 |
| `vendor_data` | 你为该企业设定的标识符。将会话与[企业实体](https://docs.didit.me/zh/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/zh/sessions-api/create-session.md)。## 发送托管验证链接响应中的 `url` 是托管验证链接。发送方式如下：- 通过你自己的平台发送邮件。
- 以链接形式嵌入你的入驻界面。
- 在应用内 webview 中打开（iOS / Android / React Native）。你可以通过[白标](https://docs.didit.me/zh/console/white-label.md)**自定义**托管体验，包括 Logo、颜色、域名和邮件模板。## 轮询与 Webhook推荐使用 Webhook。处理完成后，Didit 会立即将完成事件 POST 到你订阅的 endpoint。在开发阶段，或当你的 Webhook endpoint 无法访问时，可以使用轮询：* 使用指数退避轮询 `GET /v3/session/{id}/decision/`（起始间隔 10 秒，最长间隔 60 秒）。
* 当 `status` 为 `"Approved"`、`"Declined"` 或 `"In Review"` 之一时停止轮询。> [!WARNING]
>
> 高频轮询可能触发[速率限制](https://docs.didit.me/zh/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`：关联的[企业实体](https://docs.didit.me/zh/entities/businesses/overview.md)已发生变更。完整事件目录请参阅 [KYB Webhook](https://docs.didit.me/zh/business-verification/webhooks.md)。签名验证和重试机制请参阅 [Webhook 参考文档](https://docs.didit.me/zh/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/zh/business-verification/statuses.md)；有关解释决策原因的标签，请参阅 [KYB 警告](https://docs.didit.me/zh/business-verification/warnings.md)。## 重新提交流程当企业验证（KYB）会话转为 `Resubmitted`（或某项功能被标记为需要重新提交）时，企业需要上传修正后或补充的数据。你可以：- **重新发送**同一个 `url`，托管流程会从需要重新提交的环节继续。
- **重新生成失效的关键人员链接**：若某相关人员的子 KYC 会话已被删除，或在其开始前已过期，可使用[重新生成关键人员 KYC 会话](https://docs.didit.me/zh/sessions-api/regenerate-kyb-party.md)为其创建新会话。
- 在 Business Console 中**创建[案件](https://docs.didit.me/zh/transaction-monitoring/cases.md)**，在内部跟踪多次往返沟通。## 在你自己的前端运行各步骤证件和关键人员步骤也可以通过你的服务器，使用你的 API 密钥来驱动。这样，界面由你掌控，验证和决策仍由 Didit 完成。
每个调用都限定于该 KYB 会话，需要 `write:businesses` 权限（读取已提取的相关方信息时也可使用 `read:businesses` 或 `read:sessions`），并执行与托管页面相同的检查、计费和步骤推进。1) 会话处于 KYB 证件步骤时，[上传企业证件](https://docs.didit.me/zh/sessions-api/kyb-upload-documents.md)。
2) [读取证件中列出的相关方](https://docs.didit.me/zh/sessions-api/kyb-extracted-parties.md)，包括股东和股权比例，并将其展示给申请人。
3) [创建](https://docs.didit.me/zh/sessions-api/kyb-create-party-draft.md)、[编辑](https://docs.didit.me/zh/sessions-api/kyb-update-party-draft.md)和[删除](https://docs.didit.me/zh/sessions-api/kyb-delete-party-draft.md)[相关方草稿](https://docs.didit.me/zh/sessions-api/kyb-list-party-drafts.md)。草稿不会被视为已申报，也不产生费用。
4) [提交草稿](https://docs.didit.me/zh/sessions-api/kyb-submit-parties.md)。Didit 会决定哪些相关方需要验证，为每位相关方创建 KYC 会话，并返回其 `kyc_session_url`，供你发送或嵌入。
5) 与托管流程一样，从会话中读取汇总后的决策。若会话处于其他步骤时发起调用，将返回 `409 kyb_step_mismatch` 及其所在的步骤；若会话已结束，则返回 `409 kyb_session_not_writable`。## 企业档案聚合如果你在创建会话时传入 `vendor_data`，Didit 会将该企业的所有会话聚合到同一个[企业实体](https://docs.didit.me/zh/entities/businesses/overview.md)中。你可以直接使用实体的 `features` 映射，无需遍历会话，即可判断该企业当前是否已完成全面验证。优势包括：- 定期的重新 KYB 流程会追加到同一份企业档案中。
- 针对同一 `vendor_data` 进行的交易监控会携带该企业的风险背景信息。
- 关联到用户实体的实际受益人和管理人员会建立跨实体关系。## 最佳实践| 实践 | 原因 |
| - | - |
| 始终传递 `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/zh/standalone-apis/kyb-registry-search.md#处理登记服务中断)。 |
| 速率限制 | `429 Too Many Requests`，并带有 `Retry-After` 请求头。 |完整的[速率限制](https://docs.didit.me/zh/integration/rate-limiting.md)参考文档。## 后续步骤> [card] [Webhook](https://docs.didit.me/zh/business-verification/webhooks.md)
>
> 每个 KYB 事件及其 payload。> [card] [状态](https://docs.didit.me/zh/business-verification/statuses.md)
>
> 状态机参考。> [card] [响应结构](https://docs.didit.me/zh/business-verification/response-schema.md)
>
> 解读 KYB 决策结果。


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