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

# 账户入驻

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

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

## 前置条件

> [!NOTE]
>
> 开始之前，请确认你已准备好：
>
> * 一个可用的[沙盒账户](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/create-a-sandbox-account.md)
> * [API 密钥](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/create-api-keys.md)（`x-client-id` 与 `x-api-key`）

## 实体类型

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

| 实体类型 | 说明 |
| - | - |
| `INDIVIDUAL` | 面向个人的账户。 |
| `COMPANY` | 企业实体。入驻期间可能需要补充文件。 |

## 入驻流程

**1. 创建子账户**

调用 [Create SubAccount](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/create-sub-account.md) 并传入实体资料和实体类型。此请求无需选择业务线。

```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"
    },
    "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`。 |

**2. 处理初始响应**

账户不会立即激活。创建后：

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

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

**3. 监听 Webhook 通知**

UQPAY 会在账户进入验证流程后发送 Webhook 事件：

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

在控制台配置你的 Webhook 端点。配置步骤参见 [Webhook 设置](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-setting.md)。

## 账户状态生命周期

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

### `status`

跟踪账户是否可用：

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

### `verification_status`

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

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

> [!NOTE]
>
> `accountStatus` webhook 对拒绝和退回状态下发的是 `REJECTED` 和 `RETURNED`（而非
> `REJECT` / `RETURN`）。详见 [Account Status webhook](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/webhooks/account-status.md)。

## 下一步

> [card] [关联账户](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/connected-accounts.md)
>
> 使用 `x-on-behalf-of` header 代表子账户发起 API 请求。

> [card] [Create SubAccount API](https://developers-sandbox.uqpaytech.com/docs/account-center/v1.6/api-reference/create-sub-account.md)
>
> Create SubAccount 接口的完整参数说明。

> [card] [Account Status webhook](https://developers-sandbox.uqpaytech.com/docs/account-center/v1.6/webhooks/account-status.md)
>
> `onboarding.account.create` 与 `onboarding.account.update` 的事件 payload 参考。


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