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

# 一次性卡

> 签发可在首次指定交易事件后自动注销的卡片，未消费余额会自动释放回发卡账户余额。

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

[Business Visa only](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md)

## 何时使用一次性卡

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

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

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

## 支持的卡 BIN

一次性卡仅在指定的卡 BIN 上可用。沙盒测试请使用产品 BIN `40963608`。生产环境请联系 UQPAY 客户经理确认你账户下哪些 BIN 启用了一次性卡功能。

如果你在调用 [创建卡片](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 时，对一个未启用该功能的 BIN 传入 `usage_type: ONE_TIME`，请求会被拒绝。

## 创建一次性卡

发起 [创建卡片](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md) 请求时，在普通卡参数基础上额外传入以下三个字段：

| 字段 | 何时必传 | 说明 |
| - | - | - |
| `usage_type` | 如需签发一次性卡，设为 `ONE_TIME`；不传时默认为 `NORMAL`。 | 选择卡片类型（普通卡或一次性卡）。 |
| `auto_cancel_trigger` | `usage_type` 为 `ONE_TIME` 时必传 | 触发卡片自动注销的交易事件。参见[注销触发模式](#cancel-trigger-modes)。 |
| `expiry_at` | `usage_type` 为 `ONE_TIME` 时必传 | 卡片的绝对失效时间；若在此时间前没有发生触发交易，卡片会自动注销。必须为未来时间。 |

### 示例

```bash theme={null}
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"
  }'
```

**响应：**

```json theme={null}
{
  "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` | 通过（余额充足时）；该商户被锁定到此卡 | 通过（余额充足时） | 拒绝 | 首次清算成功时 |

> [!NOTE]
>
> 为支持卡片绑定（card-on-file）等场景，金额低于 USD 1（或其他币种等值金额）的验证类授权不会计入触发条件，因此不会导致卡片自动注销。

## 一次性卡不支持的操作

下列接口对一次性卡返回 HTTP 400：

* [更新卡片](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-card.md) —— 修改 `card_limit` 时
* [卡片充值](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/card-recharge.md)
* [卡片提现](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/card-withdraw.md)
* [绑定卡片](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/assign-card.md) —— 将卡片重新绑定到其他持卡人时

错误响应示例：

```json theme={null}
{
  "code": "400",
  "message": "This operation cannot be performed on One-Time Card."
}
```

## 一次性卡注销后的处理

* 卡片直接转为 `CANCELLED` 状态，不会先经过 `PRE_CANCEL` 过渡（与手动注销普通卡的[流程](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-lifecycle.md)不同），且无法再次激活。
* 任何未消费的可用余额会自动释放回你的发卡账户余额。
* 卡片记录会保留，可通过 `card_id` 查询用于对账。
* 已注销的一次性卡仍可接收退款与冲正；退款金额会进入你的发卡账户余额，而不会回到已注销的卡上。

## 费用与配额

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

## 常见问题

> [accordion] 一次性卡触发注销后还能再使用吗？
>
> 不能。一旦触发注销（或 `expiry_at` 到期），卡片即永久注销，无法再次激活。

> [accordion] ON\_CAPTURE 模式下，同一张卡的第二笔授权为什么被拒？
>
> `ON_CAPTURE` 模式下，卡片会被锁定到首次授权通过的商户。如果第二笔授权来自其他商户，会被系统按规则拒绝；同一商户的后续授权在首次清算前仍会通过。

> [accordion] 卡片注销后还能接收退款吗？
>
> 可以。已注销的一次性卡仍可接收退款与冲正，退款金额会进入你的发卡账户余额。

## 相关链接

* [创建卡片](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)
* [卡片生命周期](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-lifecycle.md)
* [授权决策](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/authorization-decisions.md)
* [签发虚拟卡](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/issue-virtual-cards.md)


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