銷卡

對一張 active 虛擬卡提交不可撤銷的註銷請求。請求為同步受理 —— 卡立即進入 status=4 (closing)；實際註銷與餘額退款經 webhook + 平臺稽核非同步完成。

• 僅接受當前 AppID 賬戶名下的虛擬卡。
• 僅 status=2 (active) 的卡可銷；frozen(6) 卡需先解凍。
• 卡內餘額按套餐銷卡費規則、經平臺稽核後退回錢包 —— 退款不是即時的。

端點

項	值
Method	POST
Path	/api/v1/openapi/card/close
鑑權	HMAC
冪等鍵	不需要

無需 Idempotency-Key

銷卡受卡狀態機保護：重複提交返回 400 card_is_closing（進行中）或 400 card_already_closed（已完成），不會重複執行。提交動作本身不動資金。

請求欄位

欄位	型別	必填	說明
card_id	string	✅	card_<id> 格式 —— 須屬於當前賬戶且為虛擬卡

請求示例

{ "card_id": "card_12345" }

響應欄位

欄位	型別	說明
card_id	string	回顯
status	int	受理後的卡狀態 —— 成功恆為 4（closing）
status_desc	string	英文狀態描述 —— closing
success	bool	受理成功為 true
message	string	受理提示資訊

響應示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "card_id": "card_12345",
    "status": 4,
    "status_desc": "closing",
    "success": true,
    "message": "close request accepted"
  }
}

受理後的生命週期

1. 受理 —— 本介面返回 status=4 (closing)，卡不可再用於支付。
2. 上游註銷 —— 提供方非同步確認註銷；屆時收到 card.closed webhook，/card/info 開始返回 status=5 (closed)。
3. 退款稽核 —— 剩餘餘額（扣除套餐銷卡費）進入平臺退款稽核，稽核透過後入賬錢包；稽核拒絕會把卡恢復為 active —— 請關注 card.status_changed。

前提與規則

1. 歸屬 —— card_id 必須屬於當前賬戶，否則 404 card_not_found。
2. 卡型別 —— 僅虛擬卡（virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a）。
3. 狀態 —— 僅 status=2 (active)；frozen(6) 需先解凍（card_frozen_cannot_close）；重複提交命中 card_is_closing / card_already_closed。
4. 不可撤銷 —— 受理後無法由你取消。

典型錯誤

HTTP	message_key	說明
400	openapi_invalid_card_id	卡 ID 缺失/非法
400	openapi_card_type_not_supported	非虛擬卡型別
400	card_is_closing	已有銷卡請求進行中
400	card_already_closed	卡已註銷
400	card_frozen_cannot_close	卡已凍結 —— 先解凍
400	card_status_cannot_close	卡不在 active，不可銷卡
400	close_not_accepted_by_upstream	上游未受理，卡已恢復為 active —— 稍後重試
400	card_upstream_closed_pending_reconcile	卡已被上游直接註銷、等待人工對賬退款 —— 不可在此銷卡
400	card_config_not_found / card_type_mismatch / operation_not_supported	配置 / 卡型別問題
401	openapi_invalid_credentials	鑑權失敗
404	card_not_found	卡不存在 / 不屬於當前賬號
500	openapi_close_card_failed	服務端異常

對接易錯點與最佳實踐

對接前必讀

銷卡是後果最重的卡操作：不可撤銷、繫結上游呼叫、資金在稽核後才移動。

1. 同步上游呼叫 —— 預留至多 ~60 秒。 提交會內聯呼叫上游提供方。本端點的 HTTP 客戶端超時請設 ≥ 60 秒。
2. 客戶端超時 ≠ 銷卡失敗。 任何超時/網路錯誤後，用 /card/info 對賬：status=4/5 → 已受理（不要再當"新請求"重複提交）；status=2 → 未生效（可安全重試）。
3. 完成訊號是非同步的。 以 card.closed webhook（或輪詢到 status=5）為完成標誌 —— 同步響應只代表"已受理"。
4. 退款非即時，金額也不等於你最後看到的卡餘額。 退款過平臺稽核並扣除套餐銷卡費；稽核被拒會把卡恢復 active。對賬請以錢包入賬為準，而非銷卡前的卡餘額。
5. close_not_accepted_by_upstream 自動回滾。 收到該錯誤時卡已恢復 active，你側無需清理，稍後重試即可。
6. 重試時把 card_is_closing / card_already_closed 視為"已達目標狀態"，而非硬錯誤。