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

# 管理 UBO

> 关联公司实体的最终受益所有人（UBO），更新其所有权和角色，并终止不再适用的链接。

最终受益所有人（UBO）是指拥有或控制公司的自然人。在 Entities 中，UBO 并非独立对象，而是 `COMPANY` 实体与 `INDIVIDUAL` 实体之间的链接。

## 先决条件

* 已注册为 `COMPANY` 实体的公司。参见[创建实体](https://docs.localpayment.com/zh/docs/create-an-entity.md)。
* 每位所有者均已注册为 `INDIVIDUAL` 实体，并拥有各自的文档和文件。
* 公司及每位所有者的 `internalId`。

## 流程

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["1. 创建每位所有者<br/>POST /api/entity/v1/entities (INDIVIDUAL)"] --> B["2. 上传其证明材料"]
    C["3. 创建公司<br/>POST /api/entity/v1/entities (COMPANY)"] --> D["4. 上传公司证明材料"]
    B --> E["5. 关联每位所有者<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    D --> E
    E --> F["6. GET /api/entity/v1/entities/{companyId}<br/>uboCount, uboRequirementMet"]
    F --> G["7. Localpayment 审核<br/>公司及每位所有者"]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px
```

链接需要两个 `internalId` 值，因此请先创建实体。公司仍处于 `PENDING_KYC` 状态时，即可链接所有者。

## 链接所有者

将 Jane Doe 链接为 CEO，持股 60%：

```bash Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl -X POST https://api.stage.localpayment.com/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f", "ownershipPercentage": 60.0, "controlRole": "CEO"}'
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "4584b476-ccc6-4e98-be40-0c5082748e35",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f",
  "ownershipPercentage": 60.0,
  "controlRole": "CEO",
  "validFrom": "2024-01-15",
  "validTo": null,
  "createdAt": "2024-01-15T17:20:47Z"
}
```

将 John Doe 链接为合伙人，持股 40%。角色请使用大写发送；小写或大小写混合（`Partner`）将返回 422 `INVALID_CONTROL_ROLE`：

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "ownershipPercentage": 40,
  "controlRole": "PARTNER",
  "validFrom": "2023-06-01"
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "2c203b2b-5f92-427d-a75f-92981e2719bf",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "ownershipPercentage": 40.0,
  "controlRole": "PARTNER",
  "validFrom": "2023-06-01",
  "validTo": null,
  "createdAt": "2024-01-15T17:20:48Z"
}
```

链接后，对该公司调用[获取实体](https://docs.localpayment.com/zh/reference/get-entity.md)将返回 `uboCount` 和 `uboRequirementMet`。

## 规则

| 规则 | 行为 |
| - | - |
| 类型 | companyId 必须是 COMPANY，personId 必须是 INDIVIDUAL（422 INVALID\_ENTITY\_TYPE）。 |
| 公司状态 | 不能是 CLOSED、BLOCKED 或 REJECTED（422 ENTITY\_NOT\_ACTIVE）。处于 IN\_REVIEW 状态时，无法创建、更改或结束链接（409 ENTITY\_IN\_REVIEW）。 |
| 百分比 | 0 到 100，最多两位小数（422 INVALID\_PERCENTAGE）。百分比未知时，请发送 `null`。 |
| 角色 | [链接 UBO](https://docs.localpayment.com/zh/reference/link-ubo.md) 中列出的角色代码之一，区分大小写（422 INVALID\_CONTROL\_ROLE）。取值：`LEGAL_REPRESENTATIVE` 表示法定代表人，`AUTHORIZED_SIGNATORY` 表示依据授权委托书签字的人员，以及所有者角色，例如 `CEO`、`DIRECTOR`、`PARTNER` 或 `OWNER`（完整列表见 [KYB 要求选项列表](https://docs.localpayment.com/zh/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md#control-roles)）。 |
| 有效期 | validFrom 默认为今天。validTo 不得早于 validFrom（422 INVALID\_VALIDITY\_RANGE）。 |
| 限制 | 每家公司最多 50 个有效链接（409 UBO\_LIMIT\_EXCEEDED）。每人每家公司最多一个有效链接（409 UBO\_ALREADY\_LINKED）。 |
| 隐私 | UBO 响应仅包含标识符。使用“获取实体”命令读取人员信息。 |

两次链接同一人时出错：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Conflict",
  "instance": "/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos",
  "code": "UBO_ALREADY_LINKED",
  "correlationId": "acdfa68b-e1da-4764-84df-0a1e949d0939",
  "details": []
}
```

重试链接时，请将 `UBO_ALREADY_LINKED` 视为成功，并通过[列出公司的 UBO](https://docs.localpayment.com/zh/reference/list-company-ubos.md)读取当前链接。

## 保持链接

* **更改百分比或角色：**[更新 UBO](https://docs.localpayment.com/zh/reference/update-ubo.md)。角色无法清除：请将其更改为其他代码，或使用[结束 UBO 链接](https://docs.localpayment.com/zh/reference/end-ubo-link.md)结束该链接，然后在不带 `controlRole` 的情况下重新链接该人员。
* **终止所有权：**[结束 UBO 链接](https://docs.localpayment.com/zh/reference/end-ubo-link.md)会将 `validTo` 设置为今天。历史记录会保留，并可通过 `includeEnded=true` 查看。
* **从人员角度查看：**[列出人员的公司](https://docs.localpayment.com/zh/reference/list-person-ubo-companies.md)。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "items": [
    {
      "id": "4584b476-ccc6-4e98-be40-0c5082748e35",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f",
      "ownershipPercentage": 55.5,
      "controlRole": null,
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:20:47Z"
    },
    {
      "id": "2c203b2b-5f92-427d-a75f-92981e2719bf",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
      "ownershipPercentage": 40.0,
      "controlRole": "PARTNER",
      "validFrom": "2023-06-01",
      "validTo": "2024-01-15",
      "createdAt": "2024-01-15T17:20:48Z"
    }
  ]
}
```

> [!WARNING]
>
> 每位所有者都是一个拥有独立 KYC 的实体，由 Localpayment 与公司一并审核。`uboRequirementMet` 仅表示至少已链接一位所有者，并不表示所有者已获批准。

## 下一步

> [card] [跟踪审核并修复拒绝问题](https://docs.localpayment.com/zh/docs/track-review-and-fix-rejections.md)
>
> 跟进公司及每位所有者的审核进度。

> [card] [链接 UBO 参考](https://docs.localpayment.com/zh/reference/link-ubo.md)
>
> 所有请求字段、响应字段和错误代码。


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