Skip to main content

概述

錢包介面允許已認證使用者讀取儲值設定、建立付款連結、兌換儲值碼、查詢儲值記錄以及管理自動儲值。
付款和自動儲值介面會建立真實的財務操作。只能在可信伺服器端、獲得使用者明確確認後呼叫。

讀取儲值設定

展示金額或付款方式前,始終先讀取目前設定:
常用欄位包括: 這些值屬於部署和活動設定。建立付款連結前,應再次驗證所選金額。

建立付款連結

目前錢包流程接收整數美元金額以及以下付款方式:
在瀏覽器中將使用者重新導向到 pay_link。獲得付款連結並不代表餘額已經入帳;付款服務商確認完成後,系統才會入帳。
不要把系統存取權杖放入跳轉 URL,也不要將其傳送給付款服務商。

兌換儲值碼

儲值碼只能使用一次。不要記錄儲值碼,也不要重試已經成功的兌換操作。

儲值記錄

回應包含 itemspagepage_sizetotal。付款完成後,應同時重新整理儲值記錄和帳號餘額:
帳號額度使用內部單位,請按照認證與額度中的方法通過 quota_per_unit 換算。

讀取自動儲值狀態

回應欄位包括:
  • bound:是否已綁定可重複扣款的付款方式
  • card_last4:卡號末四位掩碼
  • enabled:是否已啟用自動儲值
  • threshold:觸發儲值的錢包美元餘額
  • amount:每次觸發時儲值的美元金額
  • stripe_ready:目前帳號是否可以設定自動儲值

綁定付款方式

尚未綁定付款方式時,啟動設定流程:
將使用者重新導向到 setup_link。等待付款服務商回呼後,再次呼叫 GET /api/user/auto-recharge,確認 bound: true 後才能啟用自動儲值。

設定自動儲值

綁定完成後,一次性更新三個設定:
threshold 不能為負數。目前控制台要求自動儲值的 amount 至少為 10 美元,但客戶端仍應遵守伺服器和付款服務商返回的最新限制。 如果只想關閉自動儲值而保留綁定的付款方式,請傳送相同請求內容,並將 enabled 設定為 false

刪除付款綁定

刪除綁定會同時關閉自動儲值並移除已儲存的卡片引用。呼叫前必須取得使用者明確確認。

推薦付款流程

  1. 讀取 /api/user/topup/info,驗證金額和付款方式。
  2. 只建立一次付款或綁定連結。
  3. 將使用者重新導向到傳回的連結。
  4. 將付款服務商的跳轉結果視為待確認狀態,而不是入帳證明。
  5. 輪詢 /api/user/topup/self/api/user/self/api/user/auto-recharge,直到出現預期狀態。
  6. 在應用層保證重試冪等,避免同一次使用者操作生成多個付款連結。