充值（Recharge）

最後更新：2026-04-09

功能說明

提供使用者向帳戶充值的完整流程。支援多種支付方式：銀行卡轉帳、微信支付、支付寶、USDT 加密貨幣（多協議）、EB（電子錢包）、C2C 個人轉帳、客服充值等。依商戶設定顯示可用的金額快捷選項，並支援活動優惠展示。

使用者流程

進入「我的」→ 點擊「充值」按鈕 → RechargeViewController
頁面上方展示可用支付方式（Tab 形式，RechargeTabView）
選擇支付方式後，顯示對應的金額輸入區
金額輸入區：
- 快捷金額按鈕（從 API 取得）
- 手動輸入金額
- 顯示最小/最大限額提示
點擊「立即充值」→ 進入確認頁（RechargeInfoViewController / RechargeInputInfoViewController）
確認頁顯示收款資訊（銀行帳號、二維碼等）
使用者完成轉帳後，系統等待後台確認

C2C 充值特殊流程

選擇 C2C 方式 → 顯示 C2C 信息頁（RechargeC2CInfoView）
C2C 支援彈性金額（ElasticAmountListRequest）
可上傳轉帳截圖確認（RechargeC2CUploadAlert）

客服充值

選擇「客服充值」→ 開啟客服聊天視窗（RechargeChatView）
透過 KefuRechargeView 展示客服充值提示

頁面跳轉

「我的」首頁充值按鈕 → RechargeViewController
RechargeViewController 點擊「立即充值」→ RechargeInfoViewController 或 RechargeInputInfoViewController
充值頁客服按鈕 → 路由 WL://OpenLiveChatVC → 客服選擇器

技術視角（開發看這裡）

相關檔案

類型	檔案路徑
ViewController	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/C/RechargeViewController.swift`
ViewController	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/C/RechargeInfoViewController.swift`
ViewController	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/C/RechargeInputInfoViewController.swift`
Model	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/M/PaymentMethodModel.swift`
Model	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/M/RechargeFastConfigModel.swift`
Model	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/M/RechargeOperateModel.swift`
Model	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/M/RecharegeStatusModel.swift`
Model	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/M/RechargePaymentIdType.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Tab/RechargeTabView.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeContentView.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeFastAmountView.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Info/RechargeInfoView.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Info/RechargeC2CInfoView.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/CustomerService/KefuRechargeView.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/ChatView/RechargeChatView.swift`
ViewModel	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/ChatView/RechargeChatViewModel.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/RechargeC2CUploadAlert.swift`
View	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/RechargeChangeAmountAlert.swift`
Extension	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/C/RechargeViewController+BallView.swift`
Model（UserDefaults 擴展）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/M/UserDefault+Recharge.swift`
Cell（銀行選擇）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Cell/BBBankCell.swift`
Cell（支付方式）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Cell/PaymentMethodCell.swift`
View（客服充值提示）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/CustomerService/KefuRechargeTipView.swift`
View（充值活動）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Info/RechargeActivityView.swift`
View（充值底部 Cell）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Info/RechargeBottomCellView.swift`
View（充值頂部）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Info/RechargeTopView.swift`
View（USDT 資訊頂部）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Info/RechargeUsdtInfoTopView.swift`
View（浮動直播）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Live/RechargeFloatingLiveView.swift`
View（直播）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/Live/RechargeLiveView.swift`
View（基底彈窗）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/RechargeBaseAlert.swift`
View（充值失敗彈窗）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/RechargeFailAlertView.swift`
View（系統彈窗）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/RechargeSystemAlert.swift`
View（C2C 推送面板）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/STC2CPushBoardView.swift`
View（選擇銀行）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/hud/SelectBankView.swift`
View（加密貨幣確認）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/CoinRechargeCheckView.swift`
View（加密貨幣輸入）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/CyptoInputView.swift`
View（NB 支付方式）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/NBPayWayView.swift`
View（充值公告）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeAnnouncementView.swift`
View（充值底部）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeBottomView.swift`
View（充值輸入資訊）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeInputInfoView.swift`
View（充值用戶資訊輸入）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeInputUserInfoView.swift`
View（充值主視圖）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Recharge/V/input/RechargeView.swift`
API（C2C 彈性金額列表）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Recharge/STAPI+ElasticAmountListRequest.swift`
API（充值代碼）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Recharge/STAPI+RechargeCodeRequest.swift`
API（快捷充值列表）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Recharge/STAPI+RechargeFastListRequest.swift`
API（充值運營位圖片）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Recharge/STAPI+RechargeOperatePicRequest.swift`
API（充值匯率）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Recharge/STAPI+RechargeRateRequest.swift`

API

功能說明	Namespace	Endpoint	Method	主要參數
取得快捷充值金額列表	STAPI	`api/forehead/fund/recharge/fastAmount/list`	POST	無
C2C 取得彈性快捷金額	STAPI	`api/forehead/fund/recharge/elasticAmount/list`	POST	無
提交充值訂單	STAPI	`api/forehead/fund/recharge/do/submit`	GET (URL 拼接)	`token`, `paymentId`, `merchantAppId`, `limitType`, `amount`, `bankCode`, `uid`, `device-id` 等
取得充值支付方式列表	STAPI	`api/forehead/fund/recharge/payments`	POST	無
校驗充值金額	STAPI	`api/forehead/fund/recharge/amount`	POST	金額參數
取得收款資訊	STAPI	`api/forehead/fund/recharge/payment/info`	POST	無
充值訂單狀態	STAPI	`api/forehead/fund/recharge/order/status`	POST	無
充值狀態查詢	STAPI	`api/forehead/fund/recharge/status`	POST	無
取消充值訂單	STAPI	`api/forehead/fund/recharge/cancel`	POST	無
確認付款	STAPI	`api/forehead/fund/recharge/submit/confirm/payment`	POST	無
催單	STAPI	`api/forehead/fund/recharge/submit/hasten`	POST	無
取得 USDT 即時匯率	STAPI	`api/forehead/fund/recharge/rate`	POST	`coin`
取得充值運營位圖片	STAPI	`api/forehead/system/config/images/query`	POST	`categoryId`
C2C 充值金額	STAPI	`api/forehead/fund/recharge/c2c/amount`	POST	無
USDT 匯率	STAPI	`api/forehead/fund/recharge/usdt/rate`	POST	無
充值轉帳	STAPI	`api/forehead/fund/recharge/do/transfer`	POST	無
清除充值姓名	STAPI	`api/forehead/fund/recharge/clear/name`	POST	無
取得代理充值代碼	STAPI	`api/forehead/fund/agency/recharge/getCode`	POST	無

資料模型

PaymentDataModel

欄位	類型	說明
`large`	`[PaymentMethodModel]`	大額充值方式列表
`normal`	`[PaymentMethodModel]`	普通充值方式列表
`protocols4large`	`[PaymentProtocol]`	大額協議列表（如 TRC20/ERC20）
`protocols4normal`	`[PaymentProtocol]`	普通協議列表
`c2c`	`BBMerchantModel?`	C2C 商戶資訊
`c2cOpenStatus`	`Bool`	C2C 是否開啟

PaymentMethodModel

欄位	類型	說明
`paymentId`	`Int`	支付方式 ID（對應 `RechargePaymentIdType`）
`paymentName`	`String`	支付方式名稱
`merchantList`	`[BBMerchantModel]`	商戶列表
`currentAmountOptions`	`[Int]`	可選金額選項

ElasticAmountListRequest Response

欄位	說明
`list`	`[Int]` 金額列表（元）
`amountTags`	`[String]` 金額標籤文字
`elasticAmtExpireTimeCount`	`Int` 過期時間計數

實作重點

金額匹配邏輯（getFitMerchant）：
- 固定金額類型（充值卡、微信/支付寶快捷）：從 quickAmount 陣列比對
- 範圍金額類型：遍歷 merchantList，找到包含該金額的商戶
快捷金額去重：fetchaQuickAmounts() 透過 enumerated().filter 去除重複值並排序
加密貨幣協議：USDT 支援 TRC20 / ERC20 等，透過 protocolMap 存儲，轉為 [[String: String]] 陣列使用
充值金額驗證（isAmountAvailable）：先檢查是否在 currentAmountOptions 快捷選項中，再檢查是否在 amountRange 範圍內
直播嵌入充值：RechargeFloatingLiveView / RechargeLiveView — 充值頁面可嵌入直播流
已知限制：C2C 彈性金額有過期時間限制（elasticAmtExpireTimeCount），過期後需重新請求

API 呼叫流程

進入充值頁面 (RechargeViewController)

viewDidLoad → setupRechargeContainView()
  ├─ [並行 1] POST api/forehead/system/config/images/query
  │  {categoryId:"20401,...,20415,20501,...,20507,20411,..."}
  │  → 充值運營位圖片 (快取至 UserDefaults RCHARGEDP)
  │
  └─ [並行 2] POST api/forehead/fund/recharge/payment/info
     {limitType: 0} → 普通充值支付方式
     {limitType: 1} → 大額充值支付方式
     → 回傳: normal[], large[], c2c, protocols4normal[], protocols4large[]

選擇支付方式

用戶選擇支付方式 → 無 API 呼叫 (資料已載入)

若為加密貨幣:
  └─ [API] POST api/forehead/fund/recharge/rate {coin:"USDT"}
     → 即時匯率

提交充值訂單

用戶輸入金額 → 點擊確認
  ├─ [API 1] POST api/forehead/fund/recharge/amount (選填驗證)
  │  {merchantAppId, paymentId, amount}
  │
  ├─ 加密貨幣:
  │  └─ [API 2] POST api/forehead/fund/recharge/payments {merchantId, amount}
  │
  └─ 提交訂單:
     ├─ 內部支付 (innerPay=true):
     │  └─ [API 3] POST api/forehead/fund/recharge/do/transfer
     │     {paymentId, amount, merchantAppId, limitType, bankId?, name?, cardNo?, protocol?}
     │
     └─ 第三方支付 (innerPay=false):
        └─ 開啟外部 URL: api/forehead/fund/recharge/do/submit + token 參數

充值狀態追蹤 (RechargeInfoViewController)

訂單建立成功 → 進入狀態頁
  ├─ [API, 每秒輪詢] POST api/forehead/fund/recharge/status
  │  → subStatus: 0=等待付款, 7=已收款待確認, 8=已確認
  │
  ├─ Socket 即時更新: type 407/401=失敗, 433/435/437=狀態更新
  │
  ├─ 上傳憑證 (需要時):
  │  └─ [API] POST 圖片上傳 → 取得 receiptFileId
  │
  ├─ 確認已付款:
  │  ├─ 普通: POST api/forehead/fund/recharge/submit/confirm/payment
  │  └─ C2C: POST api/forehead/fund/c2c/submit/confirm/payment
  │     {orderId, receiptFileId?}
  │
  └─ 催單 (付款超時):
     ├─ 普通: POST api/forehead/fund/recharge/submit/hasten
     └─ C2C: POST api/forehead/fund/c2c/submit/hasten

取消訂單

[API] POST api/forehead/fund/recharge/cancel {orderId}

充值（Recharge） ​

功能說明 ​

使用者流程 ​

C2C 充值特殊流程 ​

客服充值 ​

頁面跳轉 ​

技術視角（開發看這裡） ​

相關檔案 ​

API ​

資料模型 ​

PaymentDataModel ​

PaymentMethodModel ​

ElasticAmountListRequest Response ​

實作重點 ​

API 呼叫流程 ​

進入充值頁面 (RechargeViewController) ​

選擇支付方式 ​

提交充值訂單 ​

充值狀態追蹤 (RechargeInfoViewController) ​

取消訂單 ​

充值（Recharge）

功能說明

使用者流程

C2C 充值特殊流程

客服充值

頁面跳轉

技術視角（開發看這裡）

相關檔案

API

資料模型

PaymentDataModel

PaymentMethodModel

ElasticAmountListRequest Response

實作重點

API 呼叫流程

進入充值頁面 (RechargeViewController)

選擇支付方式

提交充值訂單

充值狀態追蹤 (RechargeInfoViewController)

取消訂單