冻结与解冻是两个过渡态；销卡不可逆，剩余余额由 POST /close 清退。

冻结、挂失与销卡

冻结与解冻是两个过渡态

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         ← 一次确认；剩余余额由我方清退

销卡不可逆。 POST close 会把卡内剩余全部退回可用余额（不受产品最低保留限制），到账后冻结再注销。日常 POST /v1/cards/{id}/withdrawals仍然受最低保留约束，也不能传 reason=close。

close-check 的 closePhase 说明卡在哪一步。有未结算授权时不要发close —— 等结算。

相关端点

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