解冻卡片

将一张 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；只能由施加方/客服解除。请把该结果透传给用户，而非重试循环。