跳转到主要内容

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.

每张卡都遵循从创建到注销的生命周期。你可以通过 Update Card Status 接口管理状态变更。

​
状态参考

状态说明
PENDING卡片创建请求已受理，正在处理中
ACTIVE卡片可用于交易
FROZEN所有授权都会被拒绝；卡片可重新激活
BLOCKED因可疑活动被 UQPAY 锁定
PRE_CANCEL预注销状态；授权被拒绝
CANCELLED已永久停用
FAILED卡片创建失败

​
状态流转

​
冻结卡片

冻结会临时禁用所有交易。在卡片被解除冻结之前，所有到达的授权请求都会被拒绝。 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "FROZEN"}'
响应： 
{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "order_status": "PENDING"
}
冻结生效后，会触发一次 card.status.update.succeeded webhook： 
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.status.update.succeeded",
  "event_id": "54daa345-889a-4488-9002-935f63b7d3c9",
  "source_id": "3f3d036e-732c-4f9e-a4b7-3019c0adf749",
  "data": {
    "card_id": "3974bad1-247b-4939-8965-3223182fba1f",
    "card_number": "46119903****1244",
    "card_status": "FROZEN",
    "update_time": "2025-07-21T21:11:06+08:00"
  }
}

​
解除冻结

要重新激活一张已冻结的卡片，把状态改回 ACTIVE： 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "ACTIVE"}'

​
注销卡片

注销不可逆，已注销的卡片无法重新激活。
把卡片状态改为 CANCELLED： 
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "CANCELLED"}'
卡片首先会进入 PRE_CANCEL 状态：
  • 所有新的授权请求都会被拒绝。
  • 此前已授权但尚未结算的交易会正常完成结算。
  • 经过 30 天等待期后，卡片进入 CANCELLED 状态。

​
注销时的余额处理

卡模式剩余余额的处理方式
Single等待期结束后，剩余余额自动退回发卡账户余额
Share无需退款 —— 没有资金转入过卡片
如要避免 30 天等待期，可以在注销卡片前，通过 Card Withdraw 接口先把剩余余额提取出来。

​
Webhook 顺序

  1. card.status.update.succeeded，card_status: PRE_CANCEL —— 注销请求发出后立即触发
  2. card.status.update.succeeded，card_status: CANCELLED —— 等待期结束后触发

​
Webhook

以下状态变更会触发 card.status.update.succeeded webhook：ACTIVE、FROZEN、BLOCKED、PRE_CANCEL、CANCELLED。 该 webhook 不会在实体卡首次激活或虚拟卡签发默认进入 ACTIVE 状态时触发 —— 这两种场景分别由 Card Created 和 Activation Status webhook 覆盖。