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

​
认证与 API Key

参见 Create API Keys 了解分步流程。Client ID 和 API Key 都在控制台的 Developer → API Keys 页面生成。API Key 仅展示一次，请立即复制保存。
x-auth-token 请求头的值必须以 Bearer 加一个空格作为前缀。例如：
漏掉 Bearer 或其后的空格都会导致此错误。Token 本身来自 Request Access Token 接口。
是。收单业务同一时间仅允许一个 Token 处于有效状态。一旦生成新 Token，旧 Token 立即失效 —— 即使还未过期。如果在轮换 Token 时存在并发请求可能仍在使用旧 Token，请协调你的刷新逻辑，让在途请求完成后再申请新 Token。Token 有效期通过响应中的 expired_at 字段表示，默认 TTL 为 30 分钟。参见 Request Access Token。
完整规则参见 Idempotent Requests，包括 24 小时的 key 生命周期和重试行为。每次新操作请使用全新的 UUID；仅在重试同一个逻辑请求时复用同一个 key。
这表示你使用的 x-client-id 不存在，或与生产环境不匹配。请确认使用的是从生产账户（https://app.uqpay.com）生成的 Client ID，而非沙盒门户（https://app-sandbox.uqpaytech.com）的凭证。两套环境使用各自独立的凭证。

​
沙盒测试

不需要。沙盒 KYC 是模拟的 —— 提交任意值都会自动通过。沙盒环境地址为 https://app-sandbox.uqpaytech.com，API 请求发往 https://api-sandbox.uqpaytech.com。
不会。沙盒环境跳过卡片校验，你可以输入任意卡号和 CVC 并完成交易。如需触发 3DS 挑战、无摩擦流程或失败等特定场景，请使用沙盒测试指南中列出的测试卡。
UQPAY 不对 merchant_order_id 的唯一性做校验 —— 可以多次提交相同的值，系统会创建多个 PaymentIntent。在 UQPAY 内部，请使用 payment_intent_id（API 返回、以 PI... 开头的 ID）作为权威订单标识。建议： 在你这侧为每笔订单分配唯一的 merchant_order_id。这样对账更简单，也可以避免上游渠道强校验唯一性带来的问题 —— 例如 Alipay CN 要求 merchant_order_id 唯一，重复提交会导致 Alipay 侧报错。

​
支付生命周期与状态

完整的 PI 和 PA 状态表、各状态触发哪些 webhook 事件，以及 PI 在 30 分钟后自动关闭的行为，参见 Core Concepts。
对于一个 PI 对应一个 PA 的常见场景，可以将 PI SUCCEEDED 作为支付成功的权威依据。但由于 PA 失败会让 PI 退回到 REQUIRES_PAYMENT_METHOD 而不是立即变为 FAILED，你还应当同时监听 PA 状态，及时感知失败。推荐做法：同时订阅 acquiring.payment_attempt.succeeded（或 acquiring.payment_intent.succeeded）和 acquiring.payment_attempt.failed webhook，显式取消的场景则使用 acquiring.cancel.succeeded。
30 分钟。完整的过期行为参见 Core Concepts — Payment Intent。
  • 取消适用于尚未进入终态的支付 —— 各支付方式的可取消规则参见 Cancellation。
  • 退款适用于已完成的支付 —— 可退条件、可退金额和手续费处理参见 Refunds。
不可以。对于卡支付，PaymentIntent 一旦完成请款并进入终态（SUCCEEDED），就无法再取消。如需撤销已完成请款的交易，必须使用退款接口。哪些支付方式在成功后仍支持取消，参见 Cancellation。

​
3D Secure 集成

完整的请求参数（包括 three_ds_action、browser_info、ip_address）以及响应处理（next_action.redirect_iframe 与 next_action.redirect_to_url 的区别）参见 3DS Integration Guide — Option 1 和 Option 2。
请检查以下几点：
  1. 未设置 return_url：3DS 场景请使用 three_ds.return_url 字段（而非顶层的 return_url）。3DS 认证和支付成功后，用户会被重定向到该 URL。
  2. Query 参数被截断：如果 return_url 带有 query 参数，请确认它们经过正确的 URL 编码且未被截断。这是已知问题，现已修复 —— 若仍出现截断，请联系技术支持。
  3. 成功与失败都会回跳：以往只有成功的支付才会跳转到 return_url，失败的会跳转到 UQPAY 的错误页。现已调整为两种结果都跳转到 return_url。你的结果页应通过 API 查询订单状态，而不是仅凭跳转本身判定支付成功。
从 Web 浏览器发起支付时，device_id 通常无法获取。该字段对 Web 场景的请求不是必填，浏览器端集成可以省略。伪造 device ID 不但没有帮助，还可能导致拒绝率升高。

​
Webhooks

分步流程参见 Webhook Settings。请按产品线（acquiring、issuing 等）分别订阅 webhook，便于保持事件筛选清晰。
  1. IP 白名单：如果你的服务器按 IP 限制入站连接，请将 UQPAY 的 webhook 源 IP 加入白名单 —— 参见 Webhooks Overview 中的 IP 白名单部分。
  2. 订阅范围：确认已在门户订阅了正确的事件类型。
  3. 多环境并存：如果你的预发和生产系统都连接 UQPAY 生产环境，可以在同一个订阅中配置多个 webhook URL。注意两个 URL 都会收到所有事件 —— 请确保系统正确处理（例如避免重复写库）。
完整的排查清单参见 Webhook Delivery Troubleshooting Guide。

​
退款

退款会从你的可用余额中扣除：
  • 已结算的订单：退款从 Available to pay out 余额扣除。
  • 未结算的订单：退款从 Available soon（待结算）余额扣除。
如果你已把可用余额全部提现、尚无新的待结算到账，那在下一个结算批次到账之前，账上的资金将不足以完成退款。
沙盒退款要求订单处于 SUCCEEDED 状态。沙盒订单不会自动结算，因此在订单达到正确状态之前发起退款可能返回 Invalid order status。若需在沙盒中测试完整的退款流程，请联系技术支持手动触发结算。如果收到 Refund is processing, please try again after，表示同一笔订单的另一个退款请求正在处理中。请等该请求完成后再提交新的退款。参见 Refunds 和 Testing in Sandbox。
部分发卡行（通常是持卡人的开户行）会拒绝退款请求。表现是退款最初处于 PROCESSING 或 INITIATED，随后变为 FAILED。常见原因是发卡行的反欺诈或合规规则 —— 与你的集成参数无关。如果退款是偶发性失败、而不是持续失败，原因通常在发卡行一侧，而非配置问题。UQPAY 会代你向卡组织提交工单，但最终结果取决于发卡行。

​
结算与对账

可下载的 CSV 格式（Payment Report 和 Settlement Report）以及每列字段的详细说明，参见结算报表。

​
POS 集成