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

​
认证与 API Key

参见 Create API Keys，了解在控制台中生成 x-client-id 和 x-api-key 的分步流程。如果看不到 Create 按钮，说明你账户的 API 功能尚未开通 —— 请联系客户经理为你启用。
该错误表示你的账户尚未开通 API 产品。请联系 UQPAY 客户经理或支持团队，为你的商户账户启用 API 访问权限。这需要 UQPAY 侧进行手动开通。
最常见的原因：
  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 限制。
该错误（"error": "Forbidden", "message": "Access to this resource is forbidden from UAT"）表示你使用的是生产环境创建的凭证，但调用了沙盒 URL；或账户尚未开通沙盒访问权限。请联系客户经理为你的账户开通沙盒访问，并提供沙盒专用的凭证。
Access Token 的有效期为 30 分钟。在生产环境和 Sandbox 中，Global Account 允许同一个 x-client-id 的多个 Token 同时有效：签发新 Token 不会使先前尚未过期的 Token 失效。请缓存并复用 Token，并根据 Token 响应中的 expired_at 字段在过期前获取新 Token。参见 Request Access Token。

​
子账户与账户结构

  • 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。
两种方式都支持。Personal（个人）和 Company（企业）子账户，既可以通过控制台创建，也可以通过 Create Sub-Account 接口创建。无论使用哪种方式，创建完成后都可以在请求头中使用 x-on-behalf-of 通过 API 管理该账户。
请将 x-on-behalf-of 设为子账户的 account_id（长 UUID）。必须使用子账户自己的 ID —— 传入父账户/主账户 ID 的话，任何接口都不会返回该子账户的数据。Deposit 查询的情况：Webhook 通知里的 deposit account_id 就是子账户的 UUID。调用 deposit 详情接口时，可直接把该值作为 x-on-behalf-of 传入。
  • 短的 CB 前缀 ID（例如 CB4316632576）用于控制台界面以及部分 Webhook 字段 short_entity_id。
  • 长 UUID 用于 API 请求头（x-on-behalf-of）、接口响应体，以及调用大部分接口时的标准标识。
两种格式指向同一个账户。所有 API 调用请统一使用长 UUID。
能否创建更多虚拟账户取决于该子账户启用了哪些产品。如果子账户在入驻时未配置某些币种或地区，添加 VA 的选项可能被限制。请联系客户经理，确认该账户配置了哪些产品和币种。

​
虚拟账户创建

常见原因：
  1. x-on-behalf-of 的值虽然是子账户 ID，但该 VA 是在另一个账户下创建的。
  2. 子账户尚未审批/激活。
  3. 调用时使用的 Token 是父账户签发的，而 x-on-behalf-of 设置为一个不相关的子账户 ID。
请核对 x-on-behalf-of 的值是否与该 VA 所属的子账户 account_id 匹配，并确认该账户已完成 KYC。
Deposit 类 Webhook 包含一个 account_id 字段，值为收款子账户的 UUID。使用该 UUID 作为 x-on-behalf-of 调用 GET /api/v1/deposits/{deposit_id}，即可获取入金的完整详情，包括收款账号。建议在你自己的系统中维护 account_id → VA 账号 的映射，避免每次收到通知都查询。

​
出款（POBO）

此错误表示请求中传入的 beneficiary_id 在你当前操作的子账户上下文中不存在。请检查：
  1. x-on-behalf-of 请求头是否与创建该受益人的子账户匹配。
  2. 受益人是否已被删除。一旦删除，该 beneficiary ID 即失效。
  3. 是否混用了沙盒和生产环境的 beneficiary ID。
针对南非，所需的 clearing_system 取决于支付类型。通过本地通道为 ZAR 创建受益人时，请在 bank_details 中包含 "clearing_system": "LOCAL"，同时务必包含 routing_code_type1 字段。API 报错 'bank_details.clearing_system' is required 即表明请求体中缺失该字段。
哥伦比亚移动支付出款的 msisdn 字段必须使用 E.164 格式，需要带国际区号前缀。哥伦比亚需在本地号码前加 +57。例如本地号码 3122885049 应填为 +573122885049。请根据实际使用的清算网络确认该格式是否被接受。

​
外汇换汇

调用 GET /api/v1/conversion/conversion_dates?currency_to=X&currency_from=Y 获取该币种对的可用结算日期列表。conversion_date 字段只能使用该接口返回的日期。周末和公共假日通常会被排除在外。
表示你的账户尚未开通 FX 产品。请联系客户经理开通 FX/Conversion 功能。这是账户级别的产品配置，必须先启用，换汇相关接口才会对你可用。

​
Webhooks

参见 Check previous webhooks or re-trigger，了解如何在控制台中重新发送 Webhook 事件的分步说明。
在控制台的 Settings → Webhooks 中配置 Webhook URL。确保端点可公网访问（UQPAY 无法访问 localhost）。配置完成后，使用现有事件的 Re-Trigger 功能验证是否能正常投递。如果新的入金事件仍收不到，请确认订阅中包含了 banking 产品的 deposit.pending 和 deposit.completed 事件类型。参见 Webhooks Setup 和 Webhook Delivery Troubleshooting。
Deposit 类 Webhook 事件包含 account_id（子账户 UUID）和 deposit_id。若要获取完整的入金详情（包括收款账号），请使用 Webhook 中的 account_id 作为 x-on-behalf-of，调用 GET /api/v1/deposits/{deposit_id}。响应体中会包含收款方的账号。建议在客户入驻时就缓存 account_id → VA 账号 的映射，避免每次都查询。

​
沙盒测试

请联系 UQPAY 客户经理申请沙盒访问。他们会采取以下方式之一：
  • 为你开通沙盒账户并发送登录凭证，或
  • 引导你在 https://app-sandbox.uqpaytech.com 自助注册，然后为你的账户启用沙盒 banking 产品。
登录后，在 Settings → API Keys 创建一个 API Key。所有 API 调用请使用 https://api-sandbox.uqpaytech.com 作为 base URL。
沙盒环境中 KYC 不会自动审批。请联系 UQPAY 技术对接人，要求他们在后台手动审批子账户申请。提供 account_id（CB 前缀短 ID 或 UUID），并指明目标终态（例如 Active）。同理，若需测试 RFI 流程，可请他们把账户置为 Returned 状态，以便测试补件重新提交流程。
沙盒余额由 UQPAY 技术团队管理。请提供你的沙盒 account ID 和目标币种/金额，申请充值。

​
余额与转账

调用 List Balances 列出所有币种余额，或调用 Retrieve Balance 查询指定币种。
使用内部转账接口（POST /api/v1/transfer）。在请求体中将子账户设置为 source_account_id，将主账户设置为 target_account_id。当前认证账户必须是转账双方之一，且系统不支持子账户到子账户的直接转账。参见账户间转账。
  • OURS：手续费从你的账户余额中单独扣除，不从出款金额中扣。受益人收到完整的 payout_amount。
  • SHARED（即 SHA）：手续费在转账途中从出款金额中扣除。受益人实际收到的是 payout_amount 减去中转行费用后的金额。
若是 SWIFT 出款且希望受益人收到精确指定的金额，请使用 OURS。