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

# 集成 FAQ

> 基于真实客户反馈整理的 Global Account API 集成常见问题解答。

以下是从真实集成经验中整理出的常见问题和解决方案。若未找到对应答案，请联系你的 UQPAY 客户经理。

<h2 id="authentication-and-api-keys">认证与 API Key</h2>

<Accordion title="在哪里找到 API 凭证（x-client-id 和 x-api-key）？">
  参见 [Create API Keys](/zh/account-center/v1.6/guide/create-api-keys)，了解在控制台中生成 `x-client-id` 和 `x-api-key` 的分步流程。如果看不到 **Create** 按钮，说明你账户的 API 功能尚未开通 —— 请联系客户经理为你启用。
</Accordion>

<Accordion title="创建 API Key 时提示 `API functionality is not activated, please contact the administrator`。">
  该错误表示你的账户尚未开通 API 产品。请联系 UQPAY 客户经理或支持团队，为你的商户账户启用 API 访问权限。这需要 UQPAY 侧进行手动开通。
</Accordion>

<Accordion title="调用 Token 接口时返回 403 Forbidden，怎么回事？">
  最常见的原因：

  1. **Base URL 错误** —— 确认使用正确的环境地址。沙盒：`https://api-sandbox.uqpaytech.com`；生产：`https://api.uqpay.com`。
  2. **凭证错误** —— 沙盒凭证无法在生产使用，反之亦然。确认你的 `x-client-id` 和 `x-api-key` 是在哪个环境创建的。
  3. **IP 白名单** —— 如果你在创建 API Key 时配置了 IP 限制，来自其他 IP 的请求会被拦截。你可以在控制台的 API Key 设置中移除或更新该 IP 限制。
</Accordion>

<Accordion title="调用沙盒时返回 `Access to this resource is forbidden from UAT`。">
  该错误（`"error": "Forbidden", "message": "Access to this resource is forbidden from UAT"`）表示你使用的是生产环境创建的凭证，但调用了沙盒 URL；或账户尚未开通沙盒访问权限。请联系客户经理为你的账户开通沙盒访问，并提供沙盒专用的凭证。
</Accordion>

<Accordion title="Access Token 有效期多久？何时应该刷新？">
  Access Token 有效期为 **30 分钟**。请在过期前主动刷新 Token，而不是等到出现 401 错误再刷 —— 常见做法是每 25–29 分钟重新获取一次。不要长期缓存 Token；应用启动时以及按计划周期性地重新获取。参见 [Request Access Token](/zh/account-center/v1.6/api-reference/access-token)。
</Accordion>

***

<h2 id="sub-accounts-and-account-structure">子账户与账户结构</h2>

<Accordion title="House Account、Sub-Account 和 Virtual Account（VA）有什么区别？">
  * **House Account**（也称 **Master Account**，主账户）：你的 UQPAY 主账户。所有 API 凭证都归属于该账户。
  * **Sub-Account**（子账户）：在主账户下创建的子账户，代表你的某个终端客户或业务单元。子账户可以持有余额，并可拥有自己的虚拟账户。
  * **Virtual Account（VA，虚拟账户）**：分配给某个子账户的银行账号（例如 IBAN，或附带 Sort Code 的账号）。打入 VA 的资金会进入对应子账户的余额。

  如需通过 API 代表某个子账户发起操作，请在请求头中传入 `x-on-behalf-of`，其值为该子账户的 `account_id`（长 UUID 格式）。参见 [Virtual Account, Global Account, and Local Account](/zh/global-account/v1.6/guide/virtual-account-global-account-local-account)。
</Accordion>

<Accordion title="子账户可以通过 API 创建，还是只能通过控制台？">
  两种方式都支持。**Personal**（个人）和 **Company**（企业）子账户，既可以通过控制台创建，也可以通过 Create Sub-Account 接口创建。无论使用哪种方式，创建完成后都可以在请求头中使用 `x-on-behalf-of` 通过 API 管理该账户。
</Accordion>

<Accordion title="x-on-behalf-of 是如何工作的？可以用父账户 ID 查询子账户的数据吗？">
  请将 `x-on-behalf-of` 设为子账户的 `account_id`（长 UUID）。必须使用子账户自己的 ID —— 传入父账户/主账户 ID 的话，任何接口都不会返回该子账户的数据。

  Deposit 查询的情况：Webhook 通知里的 deposit `account_id` 就是子账户的 UUID。调用 deposit 详情接口时，可直接把该值作为 `x-on-behalf-of` 传入。
</Accordion>

<Accordion title="account_id 应该使用短的 CB 前缀 ID，还是长 UUID？">
  * 短的 `CB` 前缀 ID（例如 `CB4316632576`）用于控制台界面以及部分 Webhook 字段 `short_entity_id`。
  * 长 UUID 用于 API 请求头（`x-on-behalf-of`）、接口响应体，以及调用大部分接口时的标准标识。

  两种格式指向同一个账户。所有 API 调用请统一使用长 UUID。
</Accordion>

<Accordion title="创建的子账户只有一个 VA，也没有 `Add VA` 按钮，为什么？">
  能否创建更多虚拟账户取决于该子账户启用了哪些产品。如果子账户在入驻时未配置某些币种或地区，添加 VA 的选项可能被限制。请联系客户经理，确认该账户配置了哪些产品和币种。
</Accordion>

***

<h2 id="virtual-account-creation">虚拟账户创建</h2>

<Accordion title="用 x-on-behalf-of 调用 Create VA 接口时，返回结果为空（total_items: 0），为什么？">
  常见原因：

  1. `x-on-behalf-of` 的值虽然是子账户 ID，但该 VA 是在另一个账户下创建的。
  2. 子账户尚未审批/激活。
  3. 调用时使用的 Token 是父账户签发的，而 `x-on-behalf-of` 设置为一个不相关的子账户 ID。

  请核对 `x-on-behalf-of` 的值是否与该 VA 所属的子账户 `account_id` 匹配，并确认该账户已完成 KYC。
</Accordion>

<Accordion title="Webhook 中的 deposit_id 如何关联到具体是哪个 VA？">
  Deposit 类 Webhook 包含一个 `account_id` 字段，值为收款子账户的 UUID。使用该 UUID 作为 `x-on-behalf-of` 调用 `GET /api/v1/deposits/{deposit_id}`，即可获取入金的完整详情，包括收款账号。建议在你自己的系统中维护 `account_id` → VA 账号 的映射，避免每次收到通知都查询。
</Accordion>

***

<h2 id="payouts-pobo">出款（POBO）</h2>

<Accordion title="提交出款时返回 `beneficiary account not exists`，但 beneficiary ID 看起来是正确的。">
  此错误表示请求中传入的 `beneficiary_id` 在你当前操作的子账户上下文中不存在。请检查：

  1. `x-on-behalf-of` 请求头是否与创建该受益人的子账户匹配。
  2. 受益人是否已被删除。一旦删除，该 beneficiary ID 即失效。
  3. 是否混用了沙盒和生产环境的 beneficiary ID。
</Accordion>

<Accordion title="南非（ZAR）出款的 clearing_system 应填什么？">
  针对南非，所需的 `clearing_system` 取决于支付类型。通过本地通道为 ZAR 创建受益人时，请在 `bank_details` 中包含 `"clearing_system": "LOCAL"`，同时务必包含 `routing_code_type1` 字段。API 报错 `'bank_details.clearing_system' is required` 即表明请求体中缺失该字段。
</Accordion>

<Accordion title="哥伦比亚（COP）出款失败，提示 `Field additional_info.msisdn failed on e164 validation`。正确格式是什么？">
  哥伦比亚移动支付出款的 `msisdn` 字段必须使用 E.164 格式，需要带国际区号前缀。哥伦比亚需在本地号码前加 `+57`。例如本地号码 `3122885049` 应填为 `+573122885049`。请根据实际使用的清算网络确认该格式是否被接受。
</Accordion>

***

<h2 id="fx-conversion">外汇换汇</h2>

<Accordion title="调用 Quote 接口并指定日期时返回 `conversion date is invalid`。">
  调用 `GET /api/v1/conversion/conversion_dates?currency_to=X&currency_from=Y` 获取该币种对的可用结算日期列表。`conversion_date` 字段只能使用该接口返回的日期。周末和公共假日通常会被排除在外。
</Accordion>

<Accordion title="调用换汇 Quote 接口时返回 `account not config fx product`。">
  表示你的账户尚未开通 FX 产品。请联系客户经理开通 FX/Conversion 功能。这是账户级别的产品配置，必须先启用，换汇相关接口才会对你可用。
</Accordion>

***

<h2 id="webhooks">Webhooks</h2>

<Accordion title="如何在沙盒中手动触发 Deposit Webhook 以便测试？">
  参见 [Check previous webhooks or re-trigger](/zh/account-center/v1.6/guide/webhooks-setting#check-previous-webhooks-or-re-trigger)，了解如何在控制台中重新发送 Webhook 事件的分步说明。
</Accordion>

<Accordion title="收不到 deposit.pending 或 deposit.completed Webhook，如何配置 Webhook 端点？">
  在控制台的 **Settings → Webhooks** 中配置 Webhook URL。确保端点可公网访问（UQPAY 无法访问 localhost）。配置完成后，使用现有事件的 **Re-Trigger** 功能验证是否能正常投递。如果新的入金事件仍收不到，请确认订阅中包含了 banking 产品的 `deposit.pending` 和 `deposit.completed` 事件类型。

  参见 [Webhooks Setup](/zh/account-center/v1.6/guide/webhooks-setting) 和 [Webhook Delivery Troubleshooting](/zh/account-center/v1.6/guide/webhook-delivery-troubleshooting-guide)。
</Accordion>

<Accordion title="Deposit Webhook 的 payload 里没有 VA 账号（IBAN/账号），我如何知道是哪个账户收款？">
  Deposit 类 Webhook 事件包含 `account_id`（子账户 UUID）和 `deposit_id`。若要获取完整的入金详情（包括收款账号），请使用 Webhook 中的 `account_id` 作为 `x-on-behalf-of`，调用 `GET /api/v1/deposits/{deposit_id}`。响应体中会包含收款方的账号。建议在客户入驻时就缓存 `account_id` → VA 账号 的映射，避免每次都查询。
</Accordion>

***

<h2 id="sandbox-testing">沙盒测试</h2>

<Accordion title="如何获取沙盒访问权限和凭证？">
  请联系 UQPAY 客户经理申请沙盒访问。他们会采取以下方式之一：

  * 为你开通沙盒账户并发送登录凭证，或
  * 引导你在 `https://app-sandbox.uqpaytech.com` 自助注册，然后为你的账户启用沙盒 banking 产品。

  登录后，在 **Settings → API Keys** 创建一个 API Key。所有 API 调用请使用 `https://api-sandbox.uqpaytech.com` 作为 base URL。
</Accordion>

<Accordion title="我在沙盒通过 KYC API 创建了子账户，但一直卡在非审批通过状态，如何让它通过测试？">
  沙盒环境中 KYC 不会自动审批。请联系 UQPAY 技术对接人，要求他们在后台手动审批子账户申请。提供 `account_id`（CB 前缀短 ID 或 UUID），并指明目标终态（例如 `Active`）。同理，若需测试 RFI 流程，可请他们把账户置为 `Returned` 状态，以便测试补件重新提交流程。
</Accordion>

<Accordion title="如何为沙盒账户充值余额，用于测试出款和换汇？">
  沙盒余额由 UQPAY 技术团队管理。请提供你的沙盒 account ID 和目标币种/金额，申请充值。
</Accordion>

***

<h2 id="balance-and-transfers">余额与转账</h2>

<Accordion title="如何查询某个币种的余额？">
  调用 [List Balances](/zh/global-account/v1.6/api-reference/list-balances) 列出所有币种余额，或调用 [Retrieve Balance](/zh/global-account/v1.6/api-reference/retrieve-balance) 查询指定币种。
</Accordion>

<Accordion title="如何把资金从子账户转回主账户？">
  使用内部转账接口（`POST /api/v1/transfer`）。在请求体中将子账户设置为 `source_account_id`，将主账户设置为 `target_account_id`。当前认证账户必须是转账双方之一，且系统不支持子账户到子账户的直接转账。参见[账户间转账](/zh/global-account/v1.6/guide/transfer-between-accounts)。
</Accordion>

<Accordion title="出款的 fee_paid_by（OURS vs SHARED）选项是如何生效的？">
  * `OURS`：手续费从你的账户余额中单独扣除，不从出款金额中扣。受益人收到完整的 `payout_amount`。
  * `SHARED`（即 SHA）：手续费在转账途中从出款金额中扣除。受益人实际收到的是 `payout_amount` 减去中转行费用后的金额。

  若是 SWIFT 出款且希望受益人收到精确指定的金额，请使用 `OURS`。
</Accordion>