解凍卡片

將一張 frozen（已凍結） 的虛擬卡恢復為 active，使其重新可用。

• 僅可解凍以 使用者發起的凍結（即透過 凍結卡片）凍結的卡。
• 由 風控、管理員 或 系統 凍結的卡無法在此解凍，會返回 403 —— 請聯絡你的客戶經理。
• 不涉及任何資金變動 —— 解凍無手續費。

端點

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

無需 Idempotency-Key

對未處於凍結狀態的卡重試會返回 400 card_not_frozen，而不會重複執行。此操作沒有資金影響，因此無需 Idempotency-Key 請求頭。

請求欄位

欄位	型別	必填	說明
card_id	string	✅	card_<id> —— 必須屬於你的賬號且為虛擬卡

請求示例

{ "card_id": "card_12345" }

響應欄位

欄位	型別	說明
card_id	string	回顯示卡 ID
status	int	操作之後的卡狀態 —— 成功時恆為 2（active）
status_desc	string	英文狀態描述 —— active
success	bool	成功時為 true

響應示例

{
  "code": 200,
  "message": "OK",
  "data": {
    "card_id": "card_12345",
    "status": 2,
    "status_desc": "active",
    "success": true
  }
}

前提與規則

1. 歸屬 —— card_id 必須屬於已鑑權的賬號，否則返回 404 card_not_found。
2. 卡型別 —— 僅限虛擬卡。
3. 狀態 —— 僅 status=6 (frozen) 的卡可被解凍。
4. 凍結來源 —— 僅 使用者發起 的凍結可在此撤銷。若卡是由風控 / 管理員 / 系統凍結的，請求會以對應的 403 被拒絕。

常見錯誤

HTTP	message_key	說明
400	openapi_invalid_card_id	card_id 缺失/非法
400	openapi_card_type_not_supported	該卡不是虛擬卡型別
400	card_not_frozen	卡當前未處於凍結狀態
400	recharge_unfreeze_disabled	該卡只能透過充值解凍（風控凍結），而該路徑已被停用
400	operation_not_supported	該提供商/卡型別不支援解凍
401	openapi_invalid_credentials	鑑權失敗
403	unauthorized_unfreeze_admin	由管理員凍結 —— 無法自行解凍
403	unauthorized_unfreeze_risk	由風控凍結 —— 無法自行解凍
403	unauthorized_unfreeze_system	由系統凍結 —— 無法自行解凍
404	card_not_found	卡不存在 / 不屬於當前賬號
500	openapi_unfreeze_card_failed	服務端異常

說明

• 解凍成功後，/card/info 會返回 status=2。
• 此處返回 403 表示凍結是由你以外的一方施加的；卡將保持凍結，你需聯絡客服解除。

整合常見問題與最佳實踐

1. 同步呼叫、依賴上游提供商，最長約 60 秒。 解凍會內聯呼叫上游提供商（延遲特徵與凍結相同——通常幾秒，服務端最長約 60 秒）。本介面的 HTTP 客戶端超時請設為 ≥ 60 秒。
2. 客戶端超時 ≠ 解凍失敗。 遇到任何超時/網路錯誤，用 /card/info 對賬：status=2 → 解凍已成功（繼續）；status=6 → 未生效（可安全重試）。
3. 凍結/解凍沒有 webhook。 同步響應是唯一訊號，不會發出任何非同步 card.* 回撥。以響應（或 /card/info）為準。
4. 無 Idempotency-Key，但可安全重試。 重試不做去重，但卡狀態機會保護你：對已是活躍狀態的卡再次解凍返回 400 card_not_frozen。應把 card_not_frozen 視為「已處於目標狀態」，而非硬錯誤。
5. 403 是終態——不要迴圈重試。 本介面只能解凍使用者主動發起的凍結（即經 凍結卡片 施加的凍結）。若卡被風控/管理員/系統凍結（或事後又被重新凍結），解凍會返回 403 unauthorized_unfreeze_*，且重試只會一直返回 403；只能由施加方/客服解除。請把該結果透傳給使用者，而非重試迴圈。