跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
沙盒测试

沙盒模拟 endpoint 只接受特定 BIN 的卡片。当前支持模拟的 BIN 是 40963608。其他 BIN 的卡片会返回此错误。同时请检查：
  • 卡片未被注销。已注销的卡片无法处理授权。
  • 使用了正确的沙盒 base URL：https://api-sandbox.uqpaytech.com/api
这表示你所用 BIN 的预分配卡池已耗尽。请联系你的 UQPAY 客户经理，为该 BIN 申请额外的卡片分配额度。Dashboard 中显示的卡片数量仅反映已激活的卡片，不包括整个预分配池。无法自助补充卡池。
在沙盒环境中，模拟入金需要 UQPAY 员工人工审核通过后余额才会到账。请在支持群中提交入金编号，员工会进行审核。此审核步骤在生产环境中不存在。
Assign Card 接口不能使用随机卡号。UQPAY 会为沙盒使用配置一批实体卡号并发送给你。请向你的 UQPAY 客户经理申请。

​
认证与 API 接入

Access Token 的有效期为 30 分钟。同一时间仅缓存一个 Token —— 一旦生成新 Token，之前发放的所有 Token 会立即失效，无论剩余有效期多长。请根据 Token 响应中的 expired_at 字段判断何时刷新。参见 Request Access Token。
x-on-behalf-of 请求头需要严格校验：
  • 必须为有效的 UUID 格式（例如 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be）
  • 必须对应一个有效的 Issuing 子账户 ID
  • 空值或格式错误会返回错误
如果收到 sub_account_not_found，请确认该账户 ID 属于 Issuing 业务线（而非 Banking），并且该子账户已激活。
API Key 的 IP 限制依据服务器访问 UQPAY 时的真实出口 IP 进行匹配。如果你在 VPN 或代理之后，请确保配置的 IP 与真实出口 IP 一致。内网或私有 IP（例如 192.168.x.x）不可路由，校验必定失败。
重复请求使用相同的 x-idempotency-key 会返回原请求的缓存结果 —— 不会创建新的操作。重要行为：
  • 缓存的响应保留 24 小时
  • 如果原请求失败（例如余额不足），使用相同的 key 重试会返回同样的失败 —— 即使条件已改变。在修复根本原因后重试时请使用新的 key。
  • 如果收到 504 超时，请使用相同的 key 重试 —— 服务器可能已经处理了该请求
两个常见原因：
  1. 缺少 Content-Type：上传文件时始终带上 Content-Type: multipart/form-data
  2. 重复使用幂等 key：x-idempotency-key 必须是有效的 UUID，且每次新请求都要唯一

​
持卡人

first_name 和 last_name 必须使用英文（拉丁字符）。中文或其他非拉丁字符不被接受。delivery_address 内的地址字段可以接受中文。
手机号必须匹配 country_code 的格式。请按号码的拨号区域传入 country_code，而不是持卡人的国籍。号码应为国际格式，不带开头的 0。详情参见手机号校验规则。
唯一性在账户维度强制校验。在同一 account_id 下，邮箱和手机号必须各自唯一 —— 该账户下的任意两位持卡人不得共享其中任一值。同一邮箱或手机号可以在不同 account_id 下复用。
不可以。没有 Delete Cardholder 接口。持卡人一经创建不可删除。

​
创建卡片与配置

risk_controls 参数（包括 allow_3ds_transactions）仅在特定 BIN 上支持。对不支持的 BIN 传入此参数会返回错误。同样的限制也适用于 no_pin_payment_amount。完整列表参见支持风控配置的 BIN 列表。
你的账户已达到最大创卡数量上限。请联系你的 UQPAY 客户经理提升额度。
该 BIN 或 sub-BIN 尚未为你的账户配置。请向 UQPAY 支持提供你的账户 ID，他们会分配对应的 sub-BIN 池。当 sub-BIN 池耗尽时也会出现此错误。
卡片创建时状态为 PENDING，发卡完成后会转为 ACTIVE。要检测激活状态，可以监听 card.create.succeeded webhook，或轮询 Retrieve Card 接口 —— 两种方式均可。
每张卡都有一个由平台强制执行的单笔交易消费上限。具体数值取决于你的账户配置；通过 VIP 白名单可以按卡单独提升上限。请联系你的 UQPAY 客户经理确认或调整账户的上限。
每个主账户下可创建的子账户数量有上限。具体限额取决于账户配置 —— 请联系你的 UQPAY 客户经理确认或调整。

​
卡状态与生命周期

状态说明控制方
ACTIVE卡已激活，可处理交易商户
FROZEN卡已临时冻结 —— 可通过 API 解除冻结商户
BLOCKED卡被风控锁定 —— 需 UQPAY 解除锁定系统
PRE_CANCEL卡已预注销（30 天等待期）—
CANCELLED卡已永久注销—
完整的状态转换图参见卡生命周期。
FROZEN 由商户控制：你可以通过 API 冻结和解除冻结卡片，无需联系 UQPAY。BLOCKED 由风控系统触发（例如连续的 PIN 或过期日期错误尝试）。BLOCKED 的卡只能由 UQPAY 运营解除 —— 请发送邮件至 [email protected]，附上持卡人姓名、卡 ID、当前状态和解锁原因。退款和冲正仍可入账到 FROZEN 和 BLOCKED 状态的卡。
可以。你可以在一次 API 调用中将卡片从 FROZEN 直接转为 CANCELLED，无需先恢复到 ACTIVE。
发起注销后，卡片进入 PRE_CANCEL 状态，等待期为 30 天，之后自动转为 CANCELLED。在 PRE_CANCEL 期间：
  • 卡片无法处理新交易
  • 已授权但未请款的交易可能仍会结算
  • 对于 Single 卡，等待期结束后 UQPAY 会自动将剩余余额退回商户账户
不能。必须先解除冻结（置为 ACTIVE）才能绑定或修改其限额。
虚拟卡创建成功后立即激活 —— 无需激活步骤。参见签发虚拟卡。实体卡需要通过 /api/v1/issuing/cards/activate 激活，使用绑定后由 card.activation.code webhook 下发的激活码。参见签发实体卡。

​
卡片充值与限额

行为Single 卡Share 卡
资金方式使用 recharge / withdraw 接口从发卡账户余额扣款
card_limit创建后不可修改可通过 Update Card 接口修改
费用从卡余额扣除（可能为负）从发卡账户余额扣除
卡类型的背景信息参见核心概念。
Single 模式的卡创建后不支持修改 card_limit。要调整 Single 卡的可消费金额，请改用 recharge 和 withdraw 接口。
没有。目前没有在 Banking 和 Issuing 业务线之间划款的接口。这需要通过 Dashboard 中 Issuing 区域的 Deposit 按钮手动操作。
这表示 Issuing 划款产品尚未为该子账户配置。请联系 UQPAY 运营开通。

​
交易与结算

状态说明
APPROVED交易通过
DECLINED交易拒绝
PENDING 是仅在处理过程中短暂存在的中间状态 —— 请勿据此做业务判断。请等待 issuing.transaction.authorization webhook，它始终携带最终状态。REFUNDED 状态已于 2025 年 5 月 29 日移除。
failure_reason 字段已于 2025 年 5 月 29 日重命名为 description。请更新你的集成，改读 description 字段。此变更影响：
  • List Cards Transactions 接口
  • Retrieve Cards Transaction 接口
  • card.transaction.* webhook 事件
  • 导出的交易报表
ATM 取现和普通消费的 transaction_type 都是 AUTHORIZATION。要区分，请查看 merchant_data.category_code：
  • MCC 6011 = ATM 取现
  • MCC 6011 且 billing_amount == 0 = ATM 查询余额
  • 其他 MCC 值 = 普通消费
这表示卡的 card_limit 超过了平台为你账户配置的单笔交易最大上限。请联系你的 UQPAY 客户经理通过 VIP 白名单提升上限，或将单卡限额保持在已配置上限之内。
此拒绝表示交易超过了该卡所配置的免密 / 非接触交易限额。持卡人需改用输入 PIN 的方式重试。
不能。200 响应只表示 UQPAY 收到了你的请求。真正的业务结果只由 webhook 回调保证。请始终以 webhook 为权威来源。

​
Webhooks

请检查以下常见原因：
  1. 事件订阅：确认你订阅了对应事件类型。例如，钱包绑卡的 OTP 需要订阅 card.verification.otp；交易校验需要订阅 issuing.transaction.validation。
  2. HTTP 200 响应：你的 endpoint 必须在超时时间内返回 HTTP 200。
  3. URL 可访问性：确保你的 webhook URL 可从 UQPAY 源 IP 公网访问。
完整检查清单参见 Webhook Delivery Troubleshooting Guide。
当前的重试行为参见 Retry logic。
当前需要在防火墙上放行的源 IP 列表参见 Webhooks Overview 中的 IP 白名单部分。
可以。在 Dashboard 使用 Re-Trigger 按钮可以重发单个事件。分步说明参见 Check previous webhooks or re-trigger。

​
3D Secure 与钱包支付

是否触发 3D Secure 是在收单侧结账时决定的，而非发卡侧。发卡侧开关 allow_3ds_transactions 只控制 3DS 被触发后持卡人如何完成身份验证 —— 具体来说，是允许无摩擦（无交互）流程，还是必须走需要手动输入 OTP 的挑战流程。由于触发发生在收单侧，即使 allow_3ds_transactions 为 N，交易也可能进入 3DS 流程，因此仍可能产生 3DS 验证费用。如果要完全跳过 3DS（避免相关验证费用），将卡片的 enable_3ds 设为 N。这会让卡片不注册 3DS，收单侧也就无法对该卡触发 3DS 身份验证。完整两字段模型参见 3D Secure。
钱包绑卡的 OTP 需要专门订阅 card.verification.otp 事件类型。标准的 ISSUING webhook 订阅不包含该事件。
可以。UQPAY 可在账户级别关闭向持卡人发送邮件（激活码、3DS OTP）。之后你会通过 webhook 收到这些内容，并可通过自己的渠道下发给持卡人。请联系你的客户经理配置。

​
Secure iFrame 与 PCI

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

​
实体卡

如果卡已被成功绑定，再次调用 Assign Card 接口会返回此错误。绑定操作不是幂等的 —— 请通过错误响应来识别重复。
被绑定的实体卡号所属批次未分配到你的账户。实体卡库存是按账户隔离的。请确认卡批次已登记到正确的商户账户下。