冻结与解冻是两个过渡态；销卡不可逆且必须先清空卡内资金。

冻结、挂失与销卡

冻结与解冻是两个过渡态

active ──冻结──► freezing ──► frozen ──解冻──► unfreezing ──► active

不是一个「过渡中」状态来回用。 合并成一个正是「解冻之后报卡状态无效 +充值失败」那个线上故障的成因。

⚠ 过渡态期间不要往卡里推钱。那是往一张状态未定的卡里充值。

挂失与补换

POST /v1/cards/{id}/lost          ← 挂失
POST /v1/cards/{id}/replacements  ← 补换

余额不会在新旧卡之间直接转 —— 上游没有卡间转账接口。正确顺序是：旧卡转出 → 新卡充值。

申请走不下去了：取消它

GET  /v1/cards/applications/{id}/cancel-preview   ← 先看退多少
POST /v1/cards/applications/{id}/cancel

这是唯一的自助止损路径。 在它之前，一张走不下去的申请单你只能等它自己失败（补件过期转 failed、或上游拒批），而这中间用户的钱一直冻着。

• 不需要强认证：取消是止损动作，钱是往用户账上退的方向。在他最想撤销的那一刻拦一道验证，是把工具变成障碍。（销卡刚好相反 —— 那一步不可逆。）
• 退款按阶段递减：还没报给上游时全退，进了制卡就只退一部分。所以先调 preview，让用户看见退多少再点。
• 退款分两项（refunded_issue / refunded_shipping）。开卡费与邮费的比例按阶段各算各的，合成一个数你就对不出账。

⚠ cancellable: false 时不要画那颗按钮。

stage 认不出的值原样回显，别 default 成「处理中」。

销卡

GET  /v1/cards/{id}/close-check   ← 先查能不能销
POST /v1/cards/{id}/close

销卡不可逆，且必须先清空卡内资金。 跳过清空的话，上游「自动退回」的钱回的是我方账户，而会员的卡内余额还挂着正数 —— 那笔账要人工去补。

close-check 会告诉你还差什么。别跳过它直接销 ——它是这条线上唯一一个能提前发现问题的地方。

相关端点

• GET /v1/cards/{id}/close-check
• POST /v1/cards/{id}/close
• POST /v1/cards/{id}/lost