冻结卡片

冻结一张 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 字符）

请求示例

{
  "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

响应示例

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

前提与规则

1. 归属 —— card_id 必须属于已鉴权的账号，否则返回 404 card_not_found（与"不存在"不作区分，以防枚举探测）。
2. 卡类型 —— 仅虚拟卡（virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a）可通过 OpenAPI 操作。
3. 状态 —— 仅 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。
• 如需撤销，调用 解冻卡片。只有用户发起的冻结（即本接口）才可由你自行解冻；由风控/管理员施加的冻结不可自行解冻。

集成常见问题与最佳实践

接入前必读

以下是最容易导致你系统内「卡状态 / 记账」与真实状态不一致的失败模式。

1. 同步调用、依赖上游提供商，最长约 60 秒。 冻结会内联调用上游发卡提供商。通常几秒，但可能达到 10–15 秒，服务端最长允许 60 秒。本接口的 HTTP 客户端超时请设为 ≥ 60 秒；设成 10–30 秒会诱发第 2 条问题。
2. 客户端超时 ≠ 冻结失败。 若提供商已冻结成功、而你的客户端此时超时（或连接断开），你会收到错误，但卡其实已冻结——形成静默的状态错位。切勿把超时记为「未冻结」。 遇到任何超时/网络错误，用 /card/info 对账：status=6 → 冻结已成功（继续）；status=2 → 未生效（可安全重试）。
3. 冻结/解冻没有 webhook。 同步响应是唯一信号——本操作不会发出任何异步 card.* webhook。不要等待回调；以响应（或 /card/info）为准。
4. 无 Idempotency-Key，但可安全重试。 重试不做去重（每次都会打到提供商），但卡状态机会保护你：对已冻结的卡再次冻结返回 400 card_already_frozen。应把 card_already_frozen 视为「已处于目标状态」，而非硬错误。 优先用「/card/info 对账」而非盲目重试。
5. 冻结只拦截新的支付。 它不会撤销冻结前已授权的交易，也不发生任何资金变动（无手续费、余额不变）。