Freezing and unfreezing have separate transitional states. Closure is irreversible; POST /close returns the remaining balance.

Freeze, Report Lost, and Close Cards

Freezing and Unfreezing Have Separate Transitional States

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

They do not share a generic transition state. Combining them caused a production issue where unfreezing led to an invalid-card-status error and failed top-ups.

⚠ Do not send funds to a card while it is transitioning. Its status is not yet settled.

Lost Cards and Replacements

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

Funds do not transfer directly between the old and new cards; the upstream system has no card-to-card transfer endpoint. The correct sequence is: withdraw from the old card → top up the new card.

If an Application Cannot Proceed: Cancel It

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

This is the only self-service way to stop further loss. Previously, a stalled application had to fail on its own (expired supplementary documents becoming failed, or upstream rejection), while the user's funds remained frozen.

• No step-up authentication is required: cancellation is a protective action that returns funds to the user. Adding verification at the moment the user wants to cancel would turn the remedy into an obstacle. (Card closure is different: that action is irreversible.)
• Refunds decrease by stage: a full refund is available before submission upstream; once card production begins, only a partial refund remains. Therefore, call preview first so the user sees the refund before confirming.
• The refund has two components (refunded_issue / refunded_shipping). Issuing and shipping refund proportions are calculated separately by stage. Combining them makes reconciliation impossible.

⚠ Do not show the cancellation button when cancellable: false.

Display an unrecognized stage value as returned, rather than defaulting to processing.

Close a Card

GET  /v1/cards/{id}/close-check   ← 预检：有没有未结算授权 / 编排走到哪
POST /v1/cards/{id}/close         ← 一次确认；剩余余额由我方清退

Closing a card is irreversible. POST close returns the entire remaining card balance to the available balance, ignoring the product's minimum retained balance, then freezes and closes the card after the funds arrive. Ordinary POST /v1/cards/{id}/withdrawals remain subject to the retained-balance requirement and cannot use reason=close.

closePhase in close-check indicates the current closure stage. If unsettled authorizations exist, do not send close; wait for settlement.

Related Endpoints

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