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

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

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

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

<Accordion title="模拟 API 返回 'Card does not exists'">
  沙盒模拟 endpoint 只接受特定 BIN 的卡片。当前支持模拟的 BIN 是 `40963608`。其他 BIN 的卡片会返回此错误。

  同时请检查：

  * 卡片未被注销。已注销的卡片无法处理授权。
  * 使用了正确的沙盒 base URL：`https://api-sandbox.uqpaytech.com/api`
</Accordion>

<Accordion title="沙盒中无法创建卡片：'insufficient_sub_bin'">
  这表示你所用 BIN 的预分配卡池已耗尽。请联系你的 UQPAY 客户经理，为该 BIN 申请额外的卡片分配额度。

  控制台中显示的卡片数量仅反映**已激活**的卡片，不包括整个预分配池。无法自助补充卡池。
</Accordion>

<Accordion title="沙盒入金需要人工审核">
  在沙盒环境中，模拟入金需要 UQPAY 员工人工审核通过后余额才会到账。请在支持群中提交入金编号，员工会进行审核。此审核步骤在生产环境中不存在。
</Accordion>

<Accordion title="沙盒测试如何获取实体卡号？">
  Assign Card 接口不能使用随机卡号。UQPAY 会为沙盒使用配置一批实体卡号并发送给你。请向你的 UQPAY 客户经理申请。
</Accordion>

<h2 id="authentication-and-api-setup">认证与 API 接入</h2>

<Accordion title="Access Token 有效期">
  Access Token 的有效期为 **30 分钟**。同一时间仅缓存一个 Token —— 一旦生成新 Token，之前发放的所有 Token 会立即失效，无论剩余有效期多长。

  请根据 Token 响应中的 `expired_at` 字段判断何时刷新。参见 [Request Access Token](/zh/account-center/v1.6/api-reference/access-token)。
</Accordion>

<Accordion title="错误：'x-on-behalf-of' 校验失败">
  `x-on-behalf-of` 请求头需要严格校验：

  * 必须为有效的 UUID 格式（例如 `18523f72-f4de-4f9c-bb8e-ec7d1c4f32be`）
  * 必须对应一个有效的 **Issuing** 子账户 ID
  * 空值或格式错误会返回错误

  如果收到 `sub_account_not_found`，请确认该账户 ID 属于 Issuing 业务线（而非 Banking），并且该子账户已激活。
</Accordion>

<Accordion title="API Key IP 白名单">
  API Key 的 IP 限制依据服务器访问 UQPAY 时的真实出口 IP 进行匹配。如果你在 VPN 或代理之后，请确保配置的 IP 与真实出口 IP 一致。内网或私有 IP（例如 `192.168.x.x`）不可路由，校验必定失败。
</Accordion>

<Accordion title="x-idempotency-key 是怎么工作的？">
  重复请求使用相同的 `x-idempotency-key` 会返回原请求的缓存结果 —— 不会创建新的操作。重要行为：

  * 缓存的响应保留 **24 小时**
  * 如果原请求**失败**（例如余额不足），使用相同的 key 重试会返回同样的失败 —— 即使条件已改变。在修复根本原因后重试时请使用**新的** key。
  * 如果收到 504 超时，请使用**相同的** key 重试 —— 服务器可能已经处理了该请求
</Accordion>

<Accordion title="上传 KYC 文件时出现 'Parse file failed'">
  两个常见原因：

  1. **缺少 Content-Type**：上传文件时始终带上 `Content-Type: multipart/form-data`
  2. **重复使用幂等 key**：`x-idempotency-key` 必须是有效的 UUID，且每次新请求都要唯一
</Accordion>

<h2 id="cardholders">持卡人</h2>

<Accordion title="持卡人姓名必须使用英文">
  `first_name` 和 `last_name` 必须使用英文（拉丁字符）。中文或其他非拉丁字符不被接受。`delivery_address` 内的地址字段可以接受中文。
</Accordion>

<Accordion title="错误：'invalid_phone_number'">
  手机号必须匹配 `country_code` 的格式。请按号码的拨号区域传入 `country_code`，而不是持卡人的国籍。号码应为国际格式，不带开头的 0。

  详情参见[手机号校验规则](/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder)。
</Accordion>

<Accordion title="多个持卡人可以使用相同邮箱或手机号吗？">
  唯一性在**账户维度**强制校验。在同一 `account_id` 下，邮箱和手机号必须各自唯一 —— 该账户下的任意两位持卡人不得共享其中任一值。同一邮箱或手机号可以在不同 `account_id` 下复用。
</Accordion>

<Accordion title="持卡人可以被删除吗？">
  不可以。没有 Delete Cardholder 接口。持卡人一经创建不可删除。
</Accordion>

<h2 id="card-creation-and-configuration">创建卡片与配置</h2>

<Accordion title="错误：'risk_control_not_allowed'">
  `risk_controls` 参数（包括 `allow_3ds_transactions`）仅在特定卡产品上支持。对不支持的产品传入此参数会返回错误。同样的限制也适用于 `no_pin_payment_amount`。

  详见[卡产品](/zh/card-issuance/v1.6/guide/card-products)能力矩阵。
</Accordion>

<Accordion title="错误：'card quota of account exceeds limit'">
  你的账户已达到最大创卡数量上限。请联系你的 UQPAY 客户经理提升额度。
</Accordion>

<Accordion title="错误：'card bin not config'">
  该 BIN 或 sub-BIN 尚未为你的账户配置。请向 UQPAY 支持提供你的账户 ID，他们会分配对应的 sub-BIN 池。当 sub-BIN 池耗尽时也会出现此错误。
</Accordion>

<Accordion title="卡片创建后一直处于 Pending 状态">
  卡片创建时状态为 `PENDING`，发卡完成后会转为 `ACTIVE`。要检测激活状态，可以监听 [`card.create.succeeded` webhook](/zh/card-issuance/v1.6/webhooks/card-created)，或轮询 Retrieve Card 接口 —— 两种方式均可。
</Accordion>

<Accordion title="单笔消费限额的最大值是多少？">
  每张卡都有一个由平台强制执行的单笔交易消费上限。具体数值取决于你的账户配置；通过 VIP 白名单可以按卡单独提升上限。请联系你的 UQPAY 客户经理确认或调整账户的上限。
</Accordion>

<Accordion title="子账户创建数量限制">
  每个主账户下可创建的子账户数量有上限。具体限额取决于账户配置 —— 请联系你的 UQPAY 客户经理确认或调整。
</Accordion>

<h2 id="card-status-and-lifecycle">卡状态与生命周期</h2>

<Accordion title="card_status 可能的取值有哪些？">
  | 状态           | 说明                     | 控制方 |
  | ------------ | ---------------------- | --- |
  | `ACTIVE`     | 卡已激活，可处理交易             | 商户  |
  | `FROZEN`     | 卡已临时冻结 —— 可通过 API 解除冻结 | 商户  |
  | `BLOCKED`    | 卡被风控锁定 —— 需 UQPAY 解除锁定 | 系统  |
  | `PRE_CANCEL` | 卡已预注销（30 天等待期）         | —   |
  | `CANCELLED`  | 卡已永久注销                 | —   |

  完整的状态转换图参见[卡生命周期](/zh/card-issuance/v1.6/guide/card-lifecycle)。
</Accordion>

<Accordion title="FROZEN 和 BLOCKED 有什么区别？">
  **FROZEN** 由商户控制：你可以通过 API 冻结和解除冻结卡片，无需联系 UQPAY。

  **BLOCKED** 由风控系统触发（例如连续的 PIN 或过期日期错误尝试）。BLOCKED 的卡只能由 UQPAY 运营解除 —— 请发送邮件至 `support@uqpay.com`，附上持卡人姓名、卡 ID、当前状态和解锁原因。

  退款和冲正仍可入账到 FROZEN 和 BLOCKED 状态的卡。
</Accordion>

<Accordion title="可以直接从 FROZEN 转到 CANCELLED 吗？">
  可以。你可以在一次 API 调用中将卡片从 `FROZEN` 直接转为 `CANCELLED`，无需先恢复到 `ACTIVE`。
</Accordion>

<Accordion title="卡片注销之后会发生什么？">
  发起注销后，卡片进入 `PRE_CANCEL` 状态，等待期为 30 天，之后自动转为 `CANCELLED`。在 `PRE_CANCEL` 期间：

  * 卡片无法处理新交易
  * 已授权但未请款的交易可能仍会结算
  * 对于 Single 卡，等待期结束后 UQPAY 会自动将剩余余额退回商户账户
</Accordion>

<Accordion title="能否修改 FROZEN 卡的限额？">
  不能。必须先解除冻结（置为 `ACTIVE`）才能设置或修改其限额。
</Accordion>

<Accordion title="虚拟卡与实体卡的激活">
  **虚拟卡**创建成功后立即激活 —— 无需激活步骤。参见[签发虚拟卡](/zh/card-issuance/v1.6/guide/issue-virtual-cards)。

  **实体卡**需要通过 `/api/v1/issuing/cards/activate` 激活，使用绑定后由 [`card.activation.code` webhook](/zh/card-issuance/v1.6/webhooks/activation-code) 下发的激活码。参见[签发实体卡](/zh/card-issuance/v1.6/guide/issue-physical-cards)。
</Accordion>

<h2 id="card-funding-and-limits">卡片充值与限额</h2>

<Accordion title="Single 卡与 Share 卡：限额与资金差异">
  | 行为              | Single 卡                      | Share 卡              |
  | --------------- | ----------------------------- | -------------------- |
  | **资金方式**        | 使用 `recharge` / `withdraw` 接口 | 从发卡账户余额扣款            |
  | **card\_limit** | 创建后不可修改                       | 可通过 Update Card 接口修改 |
  | **费用**          | 从卡余额扣除（可能为负）                  | 从发卡账户余额扣除            |

  卡类型的背景信息参见[核心概念](/zh/card-issuance/v1.6/guide/core-concepts)。
</Accordion>

<Accordion title="错误：'The single card not support changing card limits'">
  Single 模式的卡创建后不支持修改 `card_limit`。要调整 Single 卡的可消费金额，请改用 `recharge` 和 `withdraw` 接口。
</Accordion>

<Accordion title="有从 Banking 向 Issuing 划款的接口吗？">
  没有。目前没有在 Banking 和 Issuing 业务线之间划款的接口。这需要通过控制台中 Issuing 区域的 **Deposit** 按钮手动操作。
</Accordion>

<Accordion title="错误：账户间划款时出现 'product_not_found'">
  这表示 Issuing 划款产品尚未为该子账户配置。请联系 UQPAY 运营开通。
</Accordion>

<h2 id="transactions-and-settlement">交易与结算</h2>

<Accordion title="transaction_status 可能的取值有哪些？">
  | 状态         | 说明   |
  | ---------- | ---- |
  | `APPROVED` | 交易通过 |
  | `DECLINED` | 交易拒绝 |

  `PENDING` 是仅在处理过程中短暂存在的中间状态 —— 请勿据此做业务判断。请等待 `issuing.transaction.authorization` webhook，它始终携带最终状态。`REFUNDED` 状态已于 2025 年 5 月 29 日移除。
</Accordion>

<Accordion title="交易响应中 'failure_reason' 字段为空">
  `failure_reason` 字段已于 2025 年 5 月 29 日重命名为 `description`。请更新你的集成，改读 `description` 字段。

  此变更影响：

  * List Cards Transactions 接口
  * Retrieve Cards Transaction 接口
  * `card.transaction.*` webhook 事件
  * 导出的交易报表
</Accordion>

<Accordion title="如何区分 ATM 取现和普通消费？">
  ATM 取现和普通消费的 `transaction_type` 都是 `AUTHORIZATION`。要区分，请查看 `merchant_data.category_code`：

  * MCC `6011` = ATM 取现
  * MCC `6011` 且 `billing_amount == 0` = ATM 查询余额
  * 其他 MCC 值 = 普通消费
</Accordion>

<Accordion title="错误：'card credit limit greater than max Limit'">
  这表示卡的 `card_limit` 超过了平台为你账户配置的单笔交易最大上限。请联系你的 UQPAY 客户经理通过 VIP 白名单提升上限，或将单卡限额保持在已配置上限之内。
</Accordion>

<Accordion title="错误：'Exceed Pin Free Amount'">
  此拒绝表示交易超过了该卡所配置的免密 / 非接触交易限额。持卡人需改用输入 PIN 的方式重试。
</Accordion>

<Accordion title="recharge / withdraw 返回 200 能作为业务成功的凭据吗？">
  不能。200 响应只表示 UQPAY 收到了你的请求。真正的业务结果只由 **webhook 回调**保证。请始终以 webhook 为权威来源。
</Accordion>

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

<Accordion title="收不到 webhook 通知">
  请检查以下常见原因：

  1. **事件订阅**：确认你订阅了对应事件类型。例如，钱包绑卡的 OTP 需要订阅 `card.verification.otp`；交易校验需要订阅 `issuing.transaction.validation`。
  2. **HTTP 200 响应**：你的 endpoint 必须在超时时间内返回 HTTP `200`。
  3. **URL 可访问性**：确保你的 webhook URL 可从 UQPAY 源 IP 公网访问。

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

<Accordion title="Webhook 的重试策略是什么？">
  当前的重试行为参见 [Retry logic](/zh/account-center/v1.6/guide/webhooks-overview#retry-logic)。
</Accordion>

<Accordion title="UQPAY 的 webhook 源 IP 地址是哪些？">
  当前需要在防火墙上放行的源 IP 列表参见 [Webhooks Overview 中的 IP 白名单部分](/zh/account-center/v1.6/guide/webhooks-overview#ip-whitelist)。
</Accordion>

<Accordion title="失败的 webhook 可以重发吗？">
  可以。在控制台使用 **Re-Trigger** 按钮可以重发单个事件。分步说明参见 [Check previous webhooks or re-trigger](/zh/account-center/v1.6/guide/webhooks-setting#check-previous-webhooks-or-re-trigger)。
</Accordion>

<h2 id="3d-secure-and-wallet-payments">3D Secure 与钱包支付</h2>

<Accordion title="为什么 allow_3ds_transactions 设为 N 时仍然产生 3DS 费用？">
  是否触发 3D Secure 是在**收单侧**结账时决定的，而非发卡侧。发卡侧开关 `allow_3ds_transactions` 只控制 3DS 被触发后持卡人**如何**完成身份验证 —— 具体来说，是允许无摩擦（无交互）流程，还是必须走需要手动输入 OTP 的挑战流程。

  由于触发发生在收单侧，即使 `allow_3ds_transactions` 为 `N`，交易也可能进入 3DS 流程，因此仍可能产生 3DS 验证费用。

  如果要完全跳过 3DS（避免相关验证费用），将卡片的 `enable_3ds` 设为 `N`。这会让卡片不注册 3DS，收单侧也就无法对该卡触发 3DS 身份验证。完整两字段模型参见 [3D Secure](/zh/card-issuance/v1.6/guide/3d-secure)。
</Accordion>

<Accordion title="钱包绑卡没有收到 OTP webhook">
  钱包绑卡的 OTP 需要专门订阅 `card.verification.otp` 事件类型。标准的 `ISSUING` webhook 订阅不包含该事件。
</Accordion>

<Accordion title="能否关闭发给持卡人的邮件通知？">
  可以。UQPAY 可在账户级别关闭向持卡人发送邮件（激活码、3DS OTP）。之后你会通过 webhook 收到这些内容，并可通过自己的渠道下发给持卡人。请联系你的客户经理配置。
</Accordion>

<h2 id="secure-iframe-and-pci">Secure iFrame 与 PCI</h2>

<Accordion title="Retrieve Card Secure 要求卡片处于 ACTIVE 状态">
  `/cards/:id/secure` endpoint 要求卡片处于 `ACTIVE` 状态。对 `PENDING` 状态的卡片调用会返回 `Card does not exists`。请先等待卡片激活。
</Accordion>

<h2 id="physical-cards">实体卡</h2>

<Accordion title="重复绑定时的错误：'card has been assigned'">
  如果卡已被成功绑定，再次调用 Assign Card 接口会返回此错误。绑定操作不是幂等的 —— 请通过错误响应来识别重复。
</Accordion>

<Accordion title="错误：'card number not available for this account'">
  被绑定的实体卡号所属批次未分配到你的账户。实体卡库存是按账户隔离的。请确认卡批次已登记到正确的商户账户下。
</Accordion>