> ## 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 Acquiring API 集成常见问题解答。

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

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

<Accordion title="如何获取 API Key 和商户凭证？">
  参见 [Create API Keys](/zh/account-center/v1.6/guide/create-api-keys) 了解分步流程。Client ID 和 API Key 都在控制台的 **Developer → API Keys** 页面生成。API Key 仅展示一次，请立即复制保存。
</Accordion>

<Accordion title="调用 API 时返回 `unauthorized_error: invalid auth token format`，怎么回事？">
  `x-auth-token` 请求头的值必须以 `Bearer ` 加一个空格作为前缀。例如：

  ```
  x-auth-token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  ```

  漏掉 `Bearer ` 或其后的空格都会导致此错误。Token 本身来自 [Request Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口。
</Accordion>

<Accordion title="生成新 Token 后旧 Token 失效，这是预期行为吗？">
  是。收单业务同一时间仅允许一个 Token 处于有效状态。一旦生成新 Token，旧 Token 立即失效 —— 即使还未过期。

  如果在轮换 Token 时存在并发请求可能仍在使用旧 Token，请协调你的刷新逻辑，让在途请求完成后再申请新 Token。Token 有效期通过响应中的 `expired_at` 字段表示，默认 TTL 为 30 分钟。参见 [Request Access Token](/zh/account-center/v1.6/api-reference/access-token)。
</Accordion>

<Accordion title="`x-idempotency-key` 是什么？什么时候需要传？">
  完整规则参见 [Idempotent Requests](/zh/account-center/v1.6/guide/idempotent-requests)，包括 24 小时的 key 生命周期和重试行为。每次新操作请使用全新的 UUID；仅在重试同一个逻辑请求时复用同一个 key。
</Accordion>

<Accordion title="在生产环境请求 Access Token 时返回 `Invalid client id`（HTTP 400），该检查什么？">
  这表示你使用的 `x-client-id` 不存在，或与生产环境不匹配。请确认使用的是从**生产**账户（[https://app.uqpay.com](https://app.uqpay.com)）生成的 Client ID，而非沙盒门户（[https://app-sandbox.uqpaytech.com](https://app-sandbox.uqpaytech.com)）的凭证。两套环境使用各自独立的凭证。
</Accordion>

***

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

<Accordion title="沙盒是否需要走真实的 KYC？">
  不需要。沙盒 KYC 是模拟的 —— 提交任意值都会自动通过。沙盒环境地址为 [https://app-sandbox.uqpaytech.com](https://app-sandbox.uqpaytech.com)，API 请求发往 `https://api-sandbox.uqpaytech.com`。
</Accordion>

<Accordion title="沙盒会校验卡号和 CVC 吗？">
  不会。沙盒环境跳过卡片校验，你可以输入任意卡号和 CVC 并完成交易。如需触发 3DS 挑战、无摩擦流程或失败等特定场景，请使用[沙盒测试指南](/zh/global-acquiring/v1.6/guide/testing-in-sandbox)中列出的测试卡。
</Accordion>

<Accordion title="`merchant_order_id` 必须唯一吗？可以复用吗？">
  UQPAY 不对 `merchant_order_id` 的唯一性做校验 —— 可以多次提交相同的值，系统会创建多个 PaymentIntent。在 UQPAY 内部，请使用 `payment_intent_id`（API 返回、以 `PI...` 开头的 ID）作为权威订单标识。

  **建议：** 在你这侧为每笔订单分配唯一的 `merchant_order_id`。这样对账更简单，也可以避免上游渠道强校验唯一性带来的问题 —— 例如 Alipay CN 要求 `merchant_order_id` 唯一，重复提交会导致 Alipay 侧报错。
</Accordion>

***

<h2 id="payment-lifecycle-and-status">支付生命周期与状态</h2>

<Accordion title="PaymentIntent（PI）和 PaymentAttempt（PA）有哪些状态，哪些代表支付成功？">
  完整的 PI 和 PA 状态表、各状态触发哪些 webhook 事件，以及 PI 在 30 分钟后自动关闭的行为，参见 [Core Concepts](/zh/global-acquiring/v1.6/guide/core-concepts)。
</Accordion>

<Accordion title="应该根据 PI 还是 PA 状态判断支付成功？">
  对于一个 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`。
</Accordion>

<Accordion title="PaymentIntent 多久后自动关闭？">
  30 分钟。完整的过期行为参见 [Core Concepts — Payment Intent](/zh/global-acquiring/v1.6/guide/core-concepts)。
</Accordion>

<Accordion title="取消和退款有什么区别？">
  * **取消**适用于尚未进入终态的支付 —— 各支付方式的可取消规则参见 [Cancellation](/zh/global-acquiring/v1.6/guide/cancellation)。
  * **退款**适用于已完成的支付 —— 可退条件、可退金额和手续费处理参见 [Refunds](/zh/global-acquiring/v1.6/guide/refunds)。
</Accordion>

<Accordion title="卡支付成功请款后还可以取消吗？">
  不可以。对于**卡支付**，PaymentIntent 一旦完成请款并进入终态（`SUCCEEDED`），就无法再取消。如需撤销已完成请款的交易，必须使用退款接口。哪些支付方式在成功后仍支持取消，参见 [Cancellation](/zh/global-acquiring/v1.6/guide/cancellation)。
</Accordion>

***

<h2 id="3d-secure-integration">3D Secure 集成</h2>

<Accordion title="如何控制是否触发 3DS？需要传哪些字段？">
  完整的请求参数（包括 `three_ds_action`、`browser_info`、`ip_address`）以及响应处理（`next_action.redirect_iframe` 与 `next_action.redirect_to_url` 的区别）参见 [3DS Integration Guide — Option 1](/zh/global-acquiring/v1.6/guide/3ds-integration-guide-option-1) 和 [Option 2](/zh/global-acquiring/v1.6/guide/3ds-integration-guide-option-2)。
</Accordion>

<Accordion title="3DS 完成后用户没有跳转回我的 `return_url`，是什么原因？">
  请检查以下几点：

  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 查询订单状态，而不是仅凭跳转本身判定支付成功。
</Accordion>

<Accordion title="Web 支付时收到 `device_id is invalid`，可以不传 device ID 吗？">
  从 Web 浏览器发起支付时，`device_id` 通常无法获取。该字段对 Web 场景的请求不是必填，浏览器端集成可以省略。伪造 device ID 不但没有帮助，还可能导致拒绝率升高。
</Accordion>

***

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

<Accordion title="如何配置 webhook endpoint？">
  分步流程参见 [Webhook Settings](/zh/account-center/v1.6/guide/webhooks-setting)。请按产品线（acquiring、issuing 等）分别订阅 webhook，便于保持事件筛选清晰。
</Accordion>

<Accordion title="配置了 webhook URL 但收不到事件，该检查什么？">
  1. **IP 白名单**：如果你的服务器按 IP 限制入站连接，请将 UQPAY 的 webhook 源 IP 加入白名单 —— 参见 [Webhooks Overview 中的 IP 白名单部分](/zh/account-center/v1.6/guide/webhooks-overview#ip-whitelist)。
  2. **订阅范围**：确认已在门户订阅了正确的事件类型。
  3. **多环境并存**：如果你的预发和生产系统都连接 UQPAY 生产环境，可以在同一个订阅中配置多个 webhook URL。注意两个 URL 都会收到所有事件 —— 请确保系统正确处理（例如避免重复写库）。

  完整的排查清单参见 [Webhook Delivery Troubleshooting Guide](/zh/account-center/v1.6/guide/webhook-delivery-troubleshooting-guide)。
</Accordion>

***

<h2 id="refunds">退款</h2>

<Accordion title="发起退款时收到 `Insufficient balance`，为什么？">
  退款会从你的可用余额中扣除：

  * **已结算的订单**：退款从 `Available to pay out` 余额扣除。
  * **未结算的订单**：退款从 `Available soon`（待结算）余额扣除。

  如果你已把可用余额全部提现、尚无新的待结算到账，那在下一个结算批次到账之前，账上的资金将不足以完成退款。
</Accordion>

<Accordion title="沙盒什么时候可以发起退款？">
  沙盒退款要求订单处于 `SUCCEEDED` 状态。沙盒订单不会自动结算，因此在订单达到正确状态之前发起退款可能返回 `Invalid order status`。若需在沙盒中测试完整的退款流程，请联系技术支持手动触发结算。

  如果收到 `Refund is processing, please try again after`，表示同一笔订单的另一个退款请求正在处理中。请等该请求完成后再提交新的退款。

  参见 [Refunds](/zh/global-acquiring/v1.6/guide/refunds) 和 [Testing in Sandbox](/zh/global-acquiring/v1.6/guide/testing-in-sandbox)。
</Accordion>

<Accordion title="退款在我这侧成功，但被发卡行拒绝，怎么办？">
  部分发卡行（通常是持卡人的开户行）会拒绝退款请求。表现是退款最初处于 `PROCESSING` 或 `INITIATED`，随后变为 `FAILED`。常见原因是发卡行的反欺诈或合规规则 —— 与你的集成参数无关。

  如果退款是偶发性失败、而不是持续失败，原因通常在发卡行一侧，而非配置问题。UQPAY 会代你向卡组织提交工单，但最终结果取决于发卡行。
</Accordion>

***

<h2 id="settlement-and-reconciliation">结算与对账</h2>

<Accordion title="结算报表在哪里查看？">
  可下载的 CSV 格式（Payment Report 和 Settlement Report）以及每列字段的详细说明，参见[结算报表](/zh/global-acquiring/v1.6/guide/settlement-report)。
</Accordion>

***

<h2 id="pos-integration">POS 集成</h2>

<Accordion title="POS API 文档在哪里？">
  * [POS API Integration Guide](/zh/global-acquiring/v1.6/guide/pos-integration)
  * [Register Terminal API](/zh/global-acquiring/v1.6/api-reference/register-terminal)
  * [Get PIN Key API](/zh/global-acquiring/v1.6/api-reference/get-pin-key)
  * [Create PaymentIntent API](/zh/global-acquiring/v1.6/api-reference/create-payment-intent)
</Accordion>