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

# 关联账户

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

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

## 账户结构

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

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

## 列出关联账户

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

```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` 字段 — 在代表特定子账户发起请求时需要使用此值。

## 代表子账户操作

要把一次 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`，该请求默认视为由主账户发起。

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

## 何时不要传 `x-on-behalf-of`

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

## 错误处理

当 `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。

## 相关文档

* [账户入驻](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/account-onboarding.md)
* [List Connected Accounts API](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/list-connected-accounts.md)
* [Retrieve Account API](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/retrieve-account.md)


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