> ## 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.

# 关联账户

> 管理子账户，并通过 x-on-behalf-of header 代表子账户发起 API 请求。

UQPAY 采用主账户与子账户的双层模型。你的主账户持有 API 凭证，其下所有子账户共享同一套凭证。本页说明如何列出已关联的子账户，以及如何代表它们发起 API 请求。

<h2 id="account-architecture">账户结构</h2>

| 账户类型 | 作用                         |
| ---- | -------------------------- |
| 主账户  | 顶层账户，持有 API 凭证和 Webhook 配置 |
| 子账户  | 运行在主账户下的个人或企业实体（商户、客户或子公司） |

所有 API 凭证和 Webhook 设置均在主账户层统一配置，并对全部子账户生效。创建子账户的方法参见[账户入驻](/zh/account-center/v1.6/guide/account-onboarding)。

<h2 id="list-connected-accounts">列出关联账户</h2>

调用 [List Connected Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts) 接口获取主账户下所有关联的子账户。

```bash theme={null}
curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts?page_size=10&page_number=1" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN"
```

响应中包含账户对象数组。每个对象都带有 `account_id` 字段 — 在代表特定子账户发起请求时需要使用此值。

<h2 id="acting-on-behalf-of-a-subaccount">代表子账户操作</h2>

要把一次 API 请求限定在某个子账户的范围内，请在请求中加入 `x-on-behalf-of` header，并将其值设为该子账户的 `account_id`。

```bash theme={null}
curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_size=10&page_number=1" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN" \
  -H "x-on-behalf-of: SUBACCOUNT_ID"
```

<Note>
  如果省略 `x-on-behalf-of`，该请求默认视为由主账户发起。
</Note>

尽管 API 凭证在主账户与子账户之间共享，数据与交易上下文仍按账户隔离。`x-on-behalf-of` header 用于确保操作被限定在正确的账户范围内。

<h2 id="when-not-to-send-x-on-behalf-of">何时不要传 `x-on-behalf-of`</h2>

该 header 仅用于操作子账户范围内资源的接口。不要在主账户层级的操作上加这个 header —— 例如列出关联账户、签发 Access Token 等。如果一个请求并不针对子账户范围内的资源，请直接省略 `x-on-behalf-of`。

<h2 id="error-handling">错误处理</h2>

当 `x-on-behalf-of` 值无效，或目标子账户处于停用状态时，API 返回：

```json theme={null}
{
  "type": "account_error",
  "code": "sub_account_not_found",
  "message": "sub-account associated with the on-behalf-of not found or deactivated"
}
```

遇到此错误时，请核对 `account_id` 是否正确，并确认目标子账户处于激活状态。

<Tip>
  `account_id` 必须为 UUID 格式（例如 `18523f72-f4de-4f9c-bb8e-ec7d1c4f32be`），不能用 short reference ID。
</Tip>

<h2 id="related">相关文档</h2>

* [账户入驻](/zh/account-center/v1.6/guide/account-onboarding)
* [List Connected Accounts API](/zh/account-center/v1.6/api-reference/list-connected-accounts)
* [Retrieve Account API](/zh/account-center/v1.6/api-reference/retrieve-account)