> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 集成 FAQ

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

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

## 沙盒测试

> [accordion] 模拟 API 返回 'Card does not exists'
>
> 沙盒模拟 endpoint 只接受特定 BIN 的卡片。当前支持模拟的 BIN 是 `40963608`。其他 BIN 的卡片会返回此错误。
>
> 同时请检查：
>
> * 卡片未被注销。已注销的卡片无法处理授权。
> * 使用了正确的沙盒 base URL：`https://api-sandbox.uqpaytech.com/api`

> [accordion] 沙盒中无法创建卡片：'insufficient\_sub\_bin'
>
> 这表示你所用 BIN 的预分配卡池已耗尽。请联系你的 UQPAY 客户经理，为该 BIN 申请额外的卡片分配额度。
>
> 控制台中显示的卡片数量仅反映**已激活**的卡片，不包括整个预分配池。无法自助补充卡池。

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

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

## 认证与 API 接入

> [accordion] Access Token 有效期
>
> Access Token 的有效期为 **30 分钟**。同一时间仅缓存一个 Token —— 一旦生成新 Token，之前发放的所有 Token 会立即失效，无论剩余有效期多长。
>
> 请根据 Token 响应中的 `expired_at` 字段判断何时刷新。参见 [Request Access Token](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/access-token.md)。

> [accordion] 错误：'x-on-behalf-of' 校验失败
>
> `x-on-behalf-of` 请求头需要严格校验：
>
> * 必须为有效的 UUID 格式（例如 `18523f72-f4de-4f9c-bb8e-ec7d1c4f32be`）
> * 必须对应一个有效的 **Issuing** 子账户 ID
> * 空值或格式错误会返回错误
>
> 如果收到 `sub_account_not_found`，请确认该账户 ID 属于 Issuing 业务线（而非 Banking），并且该子账户已激活。

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

> [accordion] x-idempotency-key 是怎么工作的？
>
> 重复请求使用相同的 `x-idempotency-key` 会返回原请求的缓存结果 —— 不会创建新的操作。重要行为：
>
> * 缓存的响应保留 **24 小时**
> * 如果原请求**失败**（例如余额不足），使用相同的 key 重试会返回同样的失败 —— 即使条件已改变。在修复根本原因后重试时请使用**新的** key。
> * 如果收到 504 超时，请使用**相同的** key 重试 —— 服务器可能已经处理了该请求

> [accordion] 上传 KYC 文件时出现 'Parse file failed'
>
> 两个常见原因：
>
> 1. **缺少 Content-Type**：上传文件时始终带上 `Content-Type: multipart/form-data`
> 2. **重复使用幂等 key**：`x-idempotency-key` 必须是有效的 UUID，且每次新请求都要唯一

## 持卡人

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

> [accordion] 错误：'invalid\_phone\_number'
>
> 手机号必须匹配 `country_code` 的格式。请按号码的拨号区域传入 `country_code`，而不是持卡人的国籍。号码应为国际格式，不带开头的 0。
>
> 详情参见[手机号校验规则](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder.md)。

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

> [accordion] 持卡人可以被删除吗？
>
> 不可以。没有 Delete Cardholder 接口。持卡人一经创建不可删除。

## 创建卡片与配置

> [accordion] 错误：'risk\_control\_not\_allowed'
>
> `risk_controls` 参数（包括 `allow_3ds_transactions`）仅在特定卡产品上支持。对不支持的产品传入此参数会返回错误。同样的限制也适用于 `no_pin_payment_amount`。
>
> 详见[卡产品](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md)能力矩阵。

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

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

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

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

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

## 卡状态与生命周期

> [accordion] card\_status 可能的取值有哪些？
>
> | 状态 | 说明 | 控制方 |
> | - | - | - |
> | `ACTIVE` | 卡已激活，可处理交易 | 商户 |
> | `FROZEN` | 卡已临时冻结 —— 可通过 API 解除冻结 | 商户 |
> | `BLOCKED` | 卡被风控锁定 —— 需 UQPAY 解除锁定 | 系统 |
> | `PRE_CANCEL` | 卡已预注销（30 天等待期） | — |
> | `CANCELLED` | 卡已永久注销 | — |
>
> 完整的状态转换图参见[卡生命周期](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-lifecycle.md)。

> [accordion] FROZEN 和 BLOCKED 有什么区别？
>
> **FROZEN** 由商户控制：你可以通过 API 冻结和解除冻结卡片，无需联系 UQPAY。
>
> **BLOCKED** 由风控系统触发（例如连续的 PIN 或过期日期错误尝试）。BLOCKED 的卡只能由 UQPAY 运营解除 —— 请发送邮件至 `support@uqpay.com`，附上持卡人姓名、卡 ID、当前状态和解锁原因。
>
> 退款和冲正仍可入账到 FROZEN 和 BLOCKED 状态的卡。

> [accordion] 可以直接从 FROZEN 转到 CANCELLED 吗？
>
> 可以。你可以在一次 API 调用中将卡片从 `FROZEN` 直接转为 `CANCELLED`，无需先恢复到 `ACTIVE`。

> [accordion] 卡片注销之后会发生什么？
>
> 发起注销后，卡片进入 `PRE_CANCEL` 状态，等待期为 30 天，之后自动转为 `CANCELLED`。在 `PRE_CANCEL` 期间：
>
> * 卡片无法处理新交易
> * 已授权但未请款的交易可能仍会结算
> * 对于 Single 卡，等待期结束后 UQPAY 会自动将剩余余额退回商户账户

> [accordion] 能否修改 FROZEN 卡的限额？
>
> 不能。必须先解除冻结（置为 `ACTIVE`）才能设置或修改其限额。

> [accordion] 虚拟卡与实体卡的激活
>
> **虚拟卡**创建成功后立即激活 —— 无需激活步骤。参见[签发虚拟卡](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/issue-virtual-cards.md)。
>
> **实体卡**需要通过 `/api/v1/issuing/cards/activate` 激活，使用绑定后由 [`card.activation.code` webhook](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/activation-code) 下发的激活码。参见[签发实体卡](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/issue-physical-cards.md)。

## 卡片充值与限额

> [accordion] Single 卡与 Share 卡：限额与资金差异
>
> | 行为 | Single 卡 | Share 卡 |
> | - | - | - |
> | **资金方式** | 使用 `recharge` / `withdraw` 接口 | 从发卡账户余额扣款 |
> | **card\_limit** | 创建后不可修改 | 可通过 Update Card 接口修改 |
> | **费用** | 从卡余额扣除（可能为负） | 从发卡账户余额扣除 |
>
> 卡类型的背景信息参见[核心概念](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/core-concepts.md)。

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

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

> [accordion] 错误：账户间划款时出现 'product\_not\_found'
>
> 这表示 Issuing 划款产品尚未为该子账户配置。请联系 UQPAY 运营开通。

## 交易与结算

> [accordion] transaction\_status 可能的取值有哪些？
>
> | 状态 | 说明 |
> | - | - |
> | `APPROVED` | 交易通过 |
> | `DECLINED` | 交易拒绝 |
>
> `PENDING` 是仅在处理过程中短暂存在的中间状态 —— 请勿据此做业务判断。请等待 `issuing.transaction.authorization` webhook，它始终携带最终状态。`REFUNDED` 状态已于 2025 年 5 月 29 日移除。

> [accordion] 交易响应中 'failure\_reason' 字段为空
>
> `failure_reason` 字段已于 2025 年 5 月 29 日重命名为 `description`。请更新你的集成，改读 `description` 字段。
>
> 此变更影响：
>
> * List Cards Transactions 接口
> * Retrieve Cards Transaction 接口
> * `card.transaction.*` webhook 事件
> * 导出的交易报表

> [accordion] 如何区分 ATM 取现和普通消费？
>
> ATM 取现和普通消费的 `transaction_type` 都是 `AUTHORIZATION`。要区分，请查看 `merchant_data.category_code`：
>
> * MCC `6011` = ATM 取现
> * MCC `6011` 且 `billing_amount == 0` = ATM 查询余额
> * 其他 MCC 值 = 普通消费

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

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

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

## Webhooks

> [accordion] 收不到 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](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhook-delivery-troubleshooting-guide.md)。

> [accordion] Webhook 的重试策略是什么？
>
> 当前的重试行为参见 [Retry logic](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-overview.md#retry-logic)。

> [accordion] UQPAY 的 webhook 源 IP 地址是哪些？
>
> 当前需要在防火墙上放行的源 IP 列表参见 [Webhooks Overview 中的 IP 白名单部分](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-overview.md#ip-whitelist)。

> [accordion] 失败的 webhook 可以重发吗？
>
> 可以。在控制台使用 **Re-Trigger** 按钮可以重发单个事件。分步说明参见 [Check previous webhooks or re-trigger](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-setting.md#check-previous-webhooks-or-re-trigger)。

## 3D Secure 与钱包支付

> [accordion] 为什么 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](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/3d-secure.md)。

> [accordion] 钱包绑卡没有收到 OTP webhook
>
> 钱包绑卡的 OTP 需要专门订阅 `card.verification.otp` 事件类型。标准的 `ISSUING` webhook 订阅不包含该事件。

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

## Secure iFrame 与 PCI

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

## 实体卡

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

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

## 交易清算状态

使用交易的 `transaction_id` 调用[查询卡交易](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-cards-transaction.md)，读取成功响应中的 `settlement_status`。你可以从[卡交易列表](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-cards-transactions.md)获取 `transaction_id`；列表响应不返回 `settlement_status`。

`SETTLED` 表示 UQPAY 已记录清算，包括部分清算，不表示全额结算已完成。`UNSETTLED` 表示对于等待清算的交易尚未记录清算；`NOT_APPLICABLE` 表示该笔交易不适用清算。`UNKNOWN` 表示无法确定清算状态，不能据此认定清算尚未发生。

使用接口返回的状态，不要仅根据 `transaction_type` 和 `transaction_status` 自行推算清算状态。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.