销卡

对一张 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 视为"已达目标状态"，而非硬错误。