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

​
账户结构

账户类型作用
主账户顶层账户，持有 API 凭证和 Webhook 配置
子账户运行在主账户下的个人或企业实体（商户、客户或子公司）
所有 API 凭证和 Webhook 设置均在主账户层统一配置，并对全部子账户生效。创建子账户的方法参见账户入驻。

​
列出关联账户

调用 List Connected Accounts 接口获取主账户下所有关联的子账户。 
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。 
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"
如果省略 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 返回： 
{
  "type": "account_error",
  "code": "sub_account_not_found",
  "message": "sub-account associated with the on-behalf-of not found or deactivated"
}
遇到此错误时，请核对 account_id 是否正确，并确认目标子账户处于激活状态。
account_id 必须为 UUID 格式（例如 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be），不能用 short reference ID。