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

# 账户入驻

> 使用 UQPAY API 为商户或客户创建并入驻子账户。

如果你运营一个平台或市场，可以将下游商户或客户以子账户的形式入驻到你的 UQPAY 主账户下。每个子账户拥有独立的身份、验证状态和 UQPAY 产品访问权限。你通过 API 管理这些子账户，并在账户激活后代表它们进行操作。

<h2 id="prerequisites">前置条件</h2>

<Info>
  开始之前，请确认你已准备好：

  * 一个可用的[沙盒账户](/zh/account-center/v1.6/guide/create-a-sandbox-account)
  * [API 密钥](/zh/account-center/v1.6/guide/create-api-keys)（`x-client-id` 与 `x-api-key`）
</Info>

<h2 id="entity-types">实体类型</h2>

创建子账户时需指定实体类型：

| 实体类型         | 说明                           |
| ------------ | ---------------------------- |
| `INDIVIDUAL` | 面向个人的账户。仅在 `BANKING` 业务线下可用。 |
| `COMPANY`    | 企业实体。需提交随国家和业务线变化的附加证件。      |

对于 `COMPANY` 账户，在创建账户前调用 [Get Additional Documents](/zh/account-center/v1.6/api-reference/get-additional-documents)，获取目标国家和业务线下的必填与选填证件列表。

<h2 id="business-lines">业务线</h2>

一个子账户可以在一条或多条业务线下入驻：

* `ACQUIRING` — 受理卡支付与电子钱包支付
* `BANKING` — 发起出款并管理全球账户
* `ISSUING` — 发行并管理卡片

<h2 id="onboarding-flow">入驻流程</h2>

<Steps>
  <Step title="检查必需证件（仅 COMPANY）">
    如果你要入驻的是 `COMPANY` 实体，调用 [Get Additional Documents](/zh/account-center/v1.6/api-reference/get-additional-documents)，获取目标国家和业务线下必填与选填的证件类型列表。

    ```bash theme={null}
    curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts/get_additional?country=SG&business_code=BANKING" \
      -H "x-auth-token: YOUR_ACCESS_TOKEN"
    ```

    <Note>
      本步骤仅适用于 `COMPANY` 实体。`INDIVIDUAL` 账户在创建时无需提交附加证件。
    </Note>
  </Step>

  <Step title="创建子账户">
    调用 [Create SubAccount](/zh/account-center/v1.6/api-reference/create-sub-account) 并传入实体资料、业务线和实体类型。

    ```bash theme={null}
    curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/accounts/create_accounts" \
      -H "x-auth-token: YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "entity_type": "INDIVIDUAL",
        "nickname": "John Doe",
        "individual_info": {
          "first_name_english": "John",
          "last_name_english": "Doe",
          "nationality": "SG",
          "phone_number": "+6591234567",
          "email_address": "john.doe@example.com",
          "date_of_birth": "1990-01-15",
          "country_or_territory": "SG",
          "street_address": "1 Raffles Place",
          "city": "Singapore",
          "state": "Singapore",
          "postal_code": "048616",
          "employment_status": "Employed",
          "industry": "Information Technology/IT",
          "job_title": "Business and administration professionals",
          "company_name": "Acme Corp."
        },
        "identity_verification": {
          "identification_type": "PASSPORT",
          "identification_value": "E12345678",
          "identity_docs": ["<BASE64_ENCODED_DOCUMENT>"]
        },
        "expected_activity": {
          "account_purpose": ["PURCHASE"],
          "banking_countries": ["SG"],
          "banking_currencies": ["SGD"],
          "internationally": 1,
          "turnover_monthly": "TM001",
          "turnover_monthly_currency": "USD"
        },
        "proof_documents": {
          "proof_of_address": ["<BASE64_ENCODED_DOCUMENT>"]
        },
        "tos_acceptance": {
          "ip": "203.0.113.42",
          "date": "2026-04-15",
          "user_agent": "Mozilla/5.0"
        }
      }'
    ```

    成功响应会返回新账户的详情：

    ```json theme={null}
    {
      "account_id": "7ec16ed4-2efc-4dec-9752-29ab32d6d921",
      "short_reference_id": "CB9221063168",
      "status": "PROCESSING",
      "verification_status": "PENDING"
    }
    ```

    响应中的关键字段：

    | 字段                    | 说明                            |
    | --------------------- | ----------------------------- |
    | `account_id`          | 子账户的唯一标识。后续 API 调用中使用此值。      |
    | `short_reference_id`  | 可读的业务编号，例如 `P220406-LLCVLRM`。 |
    | `status`              | 初始值为 `PROCESSING`。            |
    | `verification_status` | 初始值为 `PENDING`。               |
  </Step>

  <Step title="处理初始响应">
    账户不会立即激活。创建后：

    * `status` 为 `PROCESSING` — 账户已创建但尚不可用。
    * `verification_status` 为 `PENDING` — 身份验证或企业验证进行中。

    妥善保存 `account_id` 供后续使用。无需轮询 — 请通过 Webhook 接收状态更新。
  </Step>

  <Step title="监听 Webhook 通知">
    UQPAY 会在账户进入验证流程后发送 Webhook 事件：

    | 事件                          | 触发时机           |
    | --------------------------- | -------------- |
    | `onboarding.account.create` | 账户创建完成、进入处理流程。 |
    | `onboarding.account.update` | 账户信息或状态发生变更。   |

    在控制台配置你的 Webhook 端点。配置步骤参见 [Webhook 设置](/zh/account-center/v1.6/guide/webhooks-setting)。
  </Step>
</Steps>

<h2 id="account-status-lifecycle">账户状态生命周期</h2>

账户创建之后，子账户会沿两条并行的状态维度推进：

<h3 id="status">`status`</h3>

跟踪账户是否可用：

| 值            | 含义              |
| ------------ | --------------- |
| `PROCESSING` | 账户已创建、审核中。尚不可用。 |
| `ACTIVE`     | 验证已通过。账户可正常使用。  |
| `INACTIVE`   | 账户存在但当前已停用。     |
| `CLOSED`     | 账户已永久关闭。        |

<h3 id="verification_status">`verification_status`</h3>

跟踪身份验证或企业验证的结果：

| 值          | 含义                     |
| ---------- | ---------------------- |
| `PENDING`  | 验证尚未完成。                |
| `APPROVED` | 验证通过。账户进入 `ACTIVE` 状态。 |
| `REJECT`   | 验证失败。账户无法激活。           |
| `RETURN`   | 提交材料被退回，需按要求修正并重新提交。   |
| `EXPIRED`  | 验证窗口期已过，未完成提交。         |

<Note>
  `accountStatus` webhook 对拒绝和退回状态下发的是 `REJECTED` 和 `RETURNED`（而非
  `REJECT` / `RETURN`）。详见 [Account Status webhook](/zh/account-center/v1.6/webhooks/account-status)。
</Note>

<h2 id="next-steps">下一步</h2>

<CardGroup cols={2}>
  <Card title="关联账户" icon="link" href="/zh/account-center/v1.6/guide/connected-accounts">
    使用 `x-on-behalf-of` header 代表子账户发起 API 请求。
  </Card>

  <Card title="Create SubAccount API" icon="code" href="/account-center/v1.6/api-reference/create-sub-account">
    Create SubAccount 接口的完整参数说明。
  </Card>

  <Card title="Get Additional Documents API" icon="file-lines" href="/account-center/v1.6/api-reference/get-additional-documents">
    按国家与业务线获取 COMPANY 入驻所需的证件列表。
  </Card>

  <Card title="Account Status webhook" icon="bell" href="/account-center/v1.6/webhooks/account-status">
    `onboarding.account.create` 与 `onboarding.account.update` 的事件 payload 参考。
  </Card>
</CardGroup>