凍結卡片
凍結一張 active（已啟用） 的虛擬卡。凍結後，該卡在你解凍之前無法用於任何支付/授權。
- 該凍結會被記錄為 使用者發起的凍結，可透過 解凍卡片 介面撤銷。
- 僅接受屬於當前
AppID賬號、且卡型別為 虛擬卡 的卡。 - 不涉及任何資金變動 —— 凍結/解凍均無手續費，也不影響卡內餘額或你的錢包。
端點
| 項 | 值 |
|---|---|
| Method | POST |
| Path | /api/v1/openapi/card/freeze |
| 鑑權 | HMAC |
| 冪等鍵 | 不需要 |
無需 Idempotency-Key
凍結天然具備冪等安全性：對已凍結的卡重試會返回 400 card_already_frozen，而不會重複執行。此操作沒有資金影響需要防護，因此無需 Idempotency-Key 請求頭。
請求欄位
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
card_id | string | ✅ | card_<id> —— 必須屬於你的賬號且為虛擬卡 |
reason | string | 可選 | 隨凍結一併記錄的自由文本原因（最長 255 字元） |
請求示例
json
{
"card_id": "card_12345",
"reason": "suspected fraud on merchant side"
}響應欄位
| 欄位 | 型別 | 說明 |
|---|---|---|
card_id | string | 回顯示卡 ID |
status | int | 操作之後的卡狀態 —— 成功時恆為 6（frozen） |
status_desc | string | 英文狀態描述 —— frozen |
success | bool | 成功時為 true |
響應示例
json
{
"code": 200,
"message": "OK",
"data": {
"card_id": "card_12345",
"status": 6,
"status_desc": "frozen",
"success": true
}
}前提與規則
- 歸屬 ——
card_id必須屬於已鑑權的賬號，否則返回404 card_not_found（與"不存在"不作區分，以防列舉探測）。 - 卡型別 —— 僅虛擬卡（
virtual_l/virtual_p/virtual_v/virtual_r/virtual_g/virtual_a）可透過 OpenAPI 操作。 - 狀態 —— 僅
status=2 (active)的卡可被凍結。pending/failed/closing/closed/ 已frozen的卡會被拒絕。
常見錯誤
| HTTP | message_key | 說明 |
|---|---|---|
| 400 | openapi_invalid_card_id | card_id 缺失/非法 |
| 400 | openapi_card_type_not_supported | 該卡不是虛擬卡型別 |
| 400 | card_already_frozen | 卡已處於凍結狀態 |
| 400 | card_status_cannot_freeze | 卡不是 active，無法凍結 |
| 400 | operation_not_supported | 該提供商/卡型別不支援凍結 |
| 401 | openapi_invalid_credentials | 鑑權失敗 |
| 404 | card_not_found | 卡不存在 / 不屬於當前賬號 |
| 500 | openapi_freeze_card_failed | 服務端異常 |
說明
- 凍結成功後，
/card/info會返回status=6。 - 如需撤銷，呼叫 解凍卡片。只有使用者發起的凍結（即本介面）才可由你自行解凍；由風控/管理員施加的凍結不可自行解凍。
整合常見問題與最佳實踐
接入前必讀
以下是最容易導致你係統內「卡狀態 / 記賬」與真實狀態不一致的失敗模式。
- 同步呼叫、依賴上游提供商，最長約 60 秒。 凍結會內聯呼叫上游髮卡提供商。通常幾秒，但可能達到 10–15 秒，服務端最長允許 60 秒。本介面的 HTTP 客戶端超時請設為 ≥ 60 秒；設成 10–30 秒會誘發第 2 條問題。
- 客戶端超時 ≠ 凍結失敗。 若提供商已凍結成功、而你的客戶端此時超時（或連線斷開），你會收到錯誤，但卡其實已凍結——形成靜默的狀態錯位。切勿把超時記為「未凍結」。 遇到任何超時/網路錯誤，用
/card/info對賬：status=6→ 凍結已成功（繼續）；status=2→ 未生效（可安全重試）。 - 凍結/解凍沒有 webhook。 同步響應是唯一訊號——本操作不會發出任何非同步
card.*webhook。不要等待回撥；以響應（或/card/info）為準。 - 無
Idempotency-Key，但可安全重試。 重試不做去重（每次都會打到提供商），但卡狀態機會保護你：對已凍結的卡再次凍結返回400 card_already_frozen。應把card_already_frozen視為「已處於目標狀態」，而非硬錯誤。 優先用「/card/info對賬」而非盲目重試。 - 凍結只攔截新的支付。 它不會撤銷凍結前已授權的交易，也不發生任何資金變動（無手續費、餘額不變）。