跳转到主要内容

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.

一次性卡是一种虚拟卡，会在你创建时选定的单一交易事件后自动注销 —— 触发事件可选首次授权通过，或首次清算（结算）成功。卡片注销后，未消费的余额会自动释放回你的发卡账户余额，且卡片无法再次激活。

​
何时使用一次性卡

场景一次性卡的适用性
单次 SaaS 或 API 扣费卡片在扣款后自动注销，商户无法静默续费或将试用转为订阅。
单次差旅或一次性报销限额在创建时即锁定，使用后卡片即注销，便于控制和对账。
单次支付防盗刷即使交易后卡号外泄，也无法被再次使用。

​
一次性卡与普通卡的区别

行为普通卡一次性卡
交易次数多次单次交易事件后即注销
限额可调整；支持充值与提现创建时锁定；不支持充值、提现或限额调整
注销方式仅支持手动注销触发事件或 expiry_at 到期时自动注销
注销后能否复用卡片无法再次激活卡片无法再次激活

​
支持的卡 BIN

一次性卡仅在指定的卡 BIN 上可用。沙箱测试请使用产品 BIN 40963608。生产环境请联系 UQPAY 客户经理确认你账户下哪些 BIN 启用了一次性卡功能。 如果你在调用 创建卡片 时，对一个未启用该功能的 BIN 传入 usage_type: ONE_TIME，请求会被拒绝。

​
创建一次性卡

发起 创建卡片 请求时，在普通卡参数基础上额外传入以下三个字段：
字段何时必传说明
usage_type如需签发一次性卡，设为 ONE_TIME；不传时默认为 NORMAL。选择卡片类型（普通卡或一次性卡）。
auto_cancel_triggerusage_type 为 ONE_TIME 时必传触发卡片自动注销的交易事件。参见注销触发模式。
expiry_atusage_type 为 ONE_TIME 时必传卡片的绝对失效时间；若在此时间前没有发生触发交易，卡片会自动注销。必须为未来时间。

​
示例

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "3a1d3ce4-977b-4f1d-8076-8d2dd59e942c",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": 50,
    "usage_type": "ONE_TIME",
    "auto_cancel_trigger": "ON_AUTH",
    "expiry_at": "2026-12-31T23:59:59+08:00"
  }'
响应： 
{
  "card_order_id": "2ee8b7c4-9458-4c6a-90cc-7f4cb4299b73",
  "card_id": "246c1e6a-90ba-4968-9b41-3a5a09395391",
  "cardholder_id": "3a1d3ce4-977b-4f1d-8076-8d2dd59e942c",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-27T15:32:17+08:00"
}
卡片初始状态为 PENDING，几秒内会变为 ACTIVE，即可用于这笔单次交易。

​
注销触发模式

请在创建时选择其中一种模式。卡片创建后无法再切换。

​
ON_AUTH —— 首次授权通过后注销

如果你希望卡片在首次被授权后即不可再用，请选择此模式。一旦有一笔授权请求通过，卡片立即注销。同一张卡后续任何授权请求 —— 包括来自同一商户的 —— 都会被拒绝。

​
ON_CAPTURE —— 首次清算成功后注销

卡片在首次授权清算（结算）前持续可用。在授权与清算之间的窗口内，卡片会被锁定到首次授权通过的商户：该商户可以对同一张卡发起再次授权（例如调整金额或重试），只要可用余额充足，这些授权都会通过；任何其他商户发起的授权都会被拒绝。 首次清算成功后，卡片自动注销。

​
判定汇总

触发模式首次授权同一商户的再次授权（清算前）其他商户的授权卡片注销时机
ON_AUTH通过（余额充足时）拒绝拒绝首次授权通过时
ON_CAPTURE通过（余额充足时）；该商户被锁定到此卡通过（余额充足时）拒绝首次清算成功时
为支持卡片绑定（card-on-file）等场景，金额低于 USD 1（或其他币种等值金额）的验证类授权不会计入触发条件，因此不会导致卡片自动注销。

​
一次性卡不支持的操作

下列接口对一次性卡返回 HTTP 400： 错误响应示例： 
{
  "code": "400",
  "message": "This operation cannot be performed on One-Time Card."
}

​
一次性卡注销后的处理

  • 卡片直接转为 CANCELLED 状态，不会先经过 PRE_CANCEL 过渡（与手动注销普通卡的流程不同），且无法再次激活。
  • 任何未消费的可用余额会自动释放回你的发卡账户余额。
  • 卡片记录会保留，可通过 card_id 查询用于对账。
  • 已注销的一次性卡仍可接收退款与冲正；退款金额会进入你的发卡账户余额，而不会回到已注销的卡上。

​
费用与配额

  • 开卡数量配额 与普通卡共享。一张一次性卡会从持卡人和机构维度的同一开卡数量上限中各占用一个名额。

​
常见问题

不能。一旦触发注销（或 expiry_at 到期），卡片即永久注销，无法再次激活。
ON_CAPTURE 模式下，卡片会被锁定到首次授权通过的商户。如果第二笔授权来自其他商户，会被系统按规则拒绝；同一商户的后续授权在首次清算前仍会通过。
可以。已注销的一次性卡仍可接收退款与冲正，退款金额会进入你的发卡账户余额。