Card top-ups are asynchronous in two stages. A successful order does not mean the funds have reached the card.
Card Top-ups and Withdrawals
Top Up a Card
POST /v1/cards/{id}/topup-quotes ← 报价（会员付多少那种资产）
POST /v1/cards/{id}/topups ← 下单
Order accepted ≠ funds on the card. Wait for the card.topup.credited event. The first_topup submitted with a card application uses this same funds-arrived event, not a separate one.
⚠ Before the credit event, do not increase the member's spending limit or display the funds as credited.
Otherwise, the limit is available before the money arrives: the member's payment is declined while your UI shows sufficient funds.
Withdraw from a Card
POST /v1/cards/{id}/withdrawals
Transfer funds from the card back to the member's wallet balance. For wallet credit, wait for card.withdraw.completed。A shared-limit card may already return completed in its 201 response; the same event is still sent.
⚠ This is a separate operation from on-chain withdrawals,
although both are called withdrawals in Chinese. Here, funds return from the card to the wallet without leaving our ledger.
Do not use this event's id with
GET /v1/withdrawals/{id}; that endpoint is for on-chain withdrawals.
Where the Card Balance Is Held
Card funds are physically held upstream and recorded in a separate bucket in our ledger. Consequently:
- Empty the card before closing it — see freezing and closing cards
- Chargeback penalties never debit this balance — they debit available funds only; any shortfall becomes a debt