充值（開發文檔）

最後更新：2026-04-10

📖 功能說明請參考充值

架構

相關檔案

ViewController（3 個）

檔案	說明
`.../Recharge/C/RechargeViewController.swift`	充值主頁
`.../Recharge/C/RechargeInfoViewController.swift`	充值確認頁
`.../Recharge/C/RechargeInputInfoViewController.swift`	充值輸入確認頁

基礎路徑：BBSport/Tab/我的/Mine/

View（25 個）

檔案	說明
`.../V/Tab/RechargeTabView.swift`	支付方式 Tab
`.../V/input/RechargeContentView.swift`	充值內容區
`.../V/input/RechargeFastAmountView.swift`	快捷金額
`.../V/input/RechargeView.swift`	充值主視圖
`.../V/input/RechargeBottomView.swift`	充值底部
`.../V/input/RechargeInputInfoView.swift`	充值輸入資訊
`.../V/input/RechargeInputUserInfoView.swift`	充值用戶資訊輸入
`.../V/input/RechargeAnnouncementView.swift`	充值公告
`.../V/input/CoinRechargeCheckView.swift`	加密貨幣確認
`.../V/input/CyptoInputView.swift`	加密貨幣輸入
`.../V/input/NBPayWayView.swift`	NB 支付方式
`.../V/Info/RechargeInfoView.swift`	充值資訊
`.../V/Info/RechargeC2CInfoView.swift`	C2C 資訊
`.../V/Info/RechargeActivityView.swift`	充值活動
`.../V/Info/RechargeBottomCellView.swift`	充值底部 Cell
`.../V/Info/RechargeTopView.swift`	充值頂部
`.../V/Info/RechargeUsdtInfoTopView.swift`	USDT 資訊頂部
`.../V/CustomerService/KefuRechargeView.swift`	客服充值
`.../V/CustomerService/KefuRechargeTipView.swift`	客服充值提示
`.../V/ChatView/RechargeChatView.swift`	客服聊天
`.../V/Live/RechargeFloatingLiveView.swift`	浮動直播
`.../V/Live/RechargeLiveView.swift`	直播
`.../V/hud/RechargeBaseAlert.swift`	基底彈窗
`.../V/hud/RechargeC2CUploadAlert.swift`	C2C 上傳彈窗
`.../V/hud/RechargeChangeAmountAlert.swift`	金額變更彈窗

基礎路徑：BBSport/Tab/我的/Mine/Recharge/

View — 其他（5 個）

檔案	說明
`.../V/hud/RechargeFailAlertView.swift`	充值失敗彈窗
`.../V/hud/RechargeSystemAlert.swift`	系統彈窗
`.../V/hud/STC2CPushBoardView.swift`	C2C 推送面板
`.../V/hud/SelectBankView.swift`	選擇銀行
`.../V/Cell/BBBankCell.swift`	銀行 Cell

基礎路徑：BBSport/Tab/我的/Mine/Recharge/

Cell / ViewModel / Extension（4 個）

檔案	說明
`.../V/Cell/PaymentMethodCell.swift`	支付方式 Cell
`.../V/ChatView/RechargeChatViewModel.swift`	聊天 ViewModel
`.../C/RechargeViewController+BallView.swift`	浮動球擴展
`.../M/UserDefault+Recharge.swift`	UserDefaults 擴展

基礎路徑：BBSport/Tab/我的/Mine/Recharge/

Model（5 個）

檔案	說明
`.../M/PaymentMethodModel.swift`	支付方式
`.../M/RechargeFastConfigModel.swift`	快捷充值配置
`.../M/RechargeOperateModel.swift`	充值運營位
`.../M/RecharegeStatusModel.swift`	充值狀態
`.../M/RechargePaymentIdType.swift`	支付方式 ID 枚舉

基礎路徑：BBSport/Tab/我的/Mine/Recharge/

API Request（5 個）

檔案	說明
`BBSport/API/STAPI/Recharge/STAPI+ElasticAmountListRequest.swift`	C2C 彈性金額
`BBSport/API/STAPI/Recharge/STAPI+RechargeCodeRequest.swift`	充值代碼
`BBSport/API/STAPI/Recharge/STAPI+RechargeFastListRequest.swift`	快捷充值列表
`BBSport/API/STAPI/Recharge/STAPI+RechargeOperatePicRequest.swift`	運營位圖片
`BBSport/API/STAPI/Recharge/STAPI+RechargeRateRequest.swift`	充值匯率

API

初始化充值

取得快捷充值金額列表

POST api/forehead/fund/recharge/fastAmount/list — urlForm — STAPI.RechargeFastListRequest

用途

載入充值頁快捷金額按鈕。

無參數，靠 Header token/uid 認證。

Response：

欄位	型別	說明
common	[Int]	普通快捷金額列表
large	[Int]	大額快捷金額列表
largeMerchant	Bool	是否顯示大額充值
showMerchant	Bool	是否讓用戶選擇通道

C2C 彈性快捷金額

POST api/forehead/fund/recharge/elasticAmount/list — urlForm — STAPI.ElasticAmountListRequest

用途

C2C 充值時取得可選金額。

無參數，靠 Header token/uid 認證。

Response：

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

關鍵數字

C2C 彈性金額有過期時間限制（elasticAmtExpireTimeCount），過期後需重新請求。

取得充值支付方式列表

POST api/forehead/fund/recharge/payment/info — POST — HttpService

用途

載入充值頁所有可用支付方式。

無參數，靠 Header token/uid 認證。

Response：

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

PaymentMethodModel 完整欄位

欄位	型別	說明
limitType	Int	限額類型（0=普通, 1=大額）
paymentId	Int（private）	支付方式 ID，透過 `paymentIdType` 轉為 `RechargePaymentIdType` 枚舉
paymentName	String	支付方式名稱
paymentLogo	String	Logo 圖片路徑（透過 `logoName` 取得完整 URL）
protocolsSort	[PaymentProtocol]	該支付方式支援的協議排序
merchantList	[BBMerchantModel]	商戶列表（含金額範圍、快捷金額等）
tempBankTransferAppId	Int	銀行轉帳臨時 AppId
tempC2CBankCardAppId	Int	C2C 銀行卡臨時 AppId
currentAmountOptions	[Int]	當前可選金額列表

計算屬性：jisuAllFastAmounts（極速轉卡快捷金額）、commonFastAmounts（推薦快捷金額）、amountRange()（可用金額範圍）

BBMerchantModel 完整欄位

欄位	型別	說明
actualOrder	Int	實際排序
aisleName	String	通道名稱
appId	Int	商戶應用 ID
channelId	Int	通道 ID
channelName	String	通道名稱
merchantId	Int	商戶 ID
bankList	[BBRechargeBankModel]	可用銀行列表（bankId, bankName）
nameList	[String]	姓名列表（NB 支付需要）
cardList	[String]	卡號列表（NB 支付需要）
quickAmount	[Int]	快捷金額選項
recommendAmount	[Int]	推薦金額選項
innerPay	Bool	是否為內部支付（true=走 /do/transfer，false=走 /do/submit 第三方）
needCardNo	Bool	是否需要輸入卡號
needName	Bool	是否需要輸入姓名
maxAmount	Double	最大充值金額
minAmount	Double	最小充值金額
protocolMap	[String: String]	加密貨幣協議映射（如 "TRC20": "提示文字"）

提交充值

校驗充值金額

POST api/forehead/fund/recharge/amount — POST — HttpService

Request：

參數	型別	必填	說明
merchantAppId	int	✅	商戶應用 ID
paymentId	int	✅	支付方式 ID
amount	double	✅	充值金額

Response： 無 data，僅含 code 和 message。

提交充值訂單（第三方跳轉）

GET api/forehead/fund/recharge/do/submit — URL 拼接 — HttpService

Request：

參數	型別	必填	說明
token	string	✅	用戶認證 token
paymentId	int	✅	支付方式 ID
merchantAppId	int	✅	商戶應用 ID
limitType	int	✅	限額類型（0=普通, 1=大額）
amount	double	✅	充值金額
bankCode	string		銀行代碼（銀行轉帳時傳入）
uid	string	✅	用戶 ID
device-id	string	✅	設備 ID

Response： 回傳第三方支付頁面 URL，由 WebView 開啟，非標準 JSON 格式。

充值內部轉帳（內部支付）

POST api/forehead/fund/recharge/do/transfer — POST — HttpService

Request：

參數	型別	必填	說明
paymentId	int	✅	支付方式 ID
amount	double	✅	充值金額
merchantAppId	int	✅	商戶應用 ID
limitType	int	✅	限額類型（0=普通, 1=大額）
appType	string	✅	App 類型
changePayType	bool	✅	是否切換支付方式
cardNo	string		銀行卡號（銀行轉帳）
name	string		持卡人姓名（銀行轉帳）
bankId	int		銀行 ID（銀行轉帳）
protocol	string		加密貨幣協議（如 TRC20）
paymentTypeId	string		支付類型 ID

Response： 同充值狀態查詢。

充值狀態追蹤

充值狀態查詢

POST api/forehead/fund/recharge/status — POST — HttpService

用途

訂單建立後每秒輪詢，追蹤充值進度。Socket 推送（type 407/401/433/435/437）也會即時更新。

無參數，靠 Header token/uid 認證。

Response：

Response 完整欄位（18 個）

欄位	型別	說明
onOff	String	是否驗證身份（0=不驗證, 1=驗證）
telephone	String	綁定的電話號碼
bankCards	[BankCards]	綁定的銀行卡列表
bankInfo	BankInfo?	銀行收款資訊（卡號、戶名、附言、支行）
digitalInfo	DigitalInfo?	數字幣收款資訊（地址、匯率、協議）
showType	String	充值方式類型
amount	Double	充值金額
orderId	String	訂單號
paymentName	String	支付方式名稱
status	Int	訂單主狀態（0=待支付, 1=成功, 2=失敗, 3=補單審核中）
subStatus	Int	訂單子狀態（7=待確認到帳, 8=超時未確認等）
expiredTtl	Int	倒計時剩餘秒數
needUploadAttachment	Bool	是否需要上傳附件
alreadyUploadAttachment	Bool	是否已上傳附件
alreadyHasten	Bool	是否已催單
hastenTTL	Int	催單倒計時
alertTime	Int	極速轉卡訂單提醒時間
agentType	Int	充值方式（0=普通, 1=代客, 2=極速轉卡）

確認付款（普通充值）

POST api/forehead/fund/recharge/submit/confirm/payment — POST — HttpService

參數	型別	必填	說明
orderId	string	✅	充值訂單 ID
receiptFileId	string		收據檔案 ID
txDetailsFileId	string		交易詳情檔案 ID

Response： 無 data，僅含 code 和 message。

確認付款（C2C）

POST api/forehead/fund/c2c/submit/confirm/payment — POST — HttpService

Request： 同普通充值確認付款。

Response： 無 data，僅含 code 和 message。

催單（普通充值）

POST api/forehead/fund/recharge/submit/hasten — POST — HttpService

參數	型別	必填	說明
orderId	string	✅	充值訂單 ID
receiptFileId	string		收據檔案 ID
txDetailsFileId	string		交易詳情檔案 ID

Response： 無 data，僅含 code 和 message。

催單（C2C）

POST api/forehead/fund/c2c/submit/hasten — POST — HttpService

Request： 同普通充值催單。

Response： 無 data，僅含 code 和 message。

取消充值訂單

POST api/forehead/fund/recharge/cancel — POST — HttpService

參數	型別	必填	說明
orderId	string	✅	充值訂單 ID

Response： 無 data，僅含 code 和 message。

匯率與運營

取得 USDT 即時匯率

POST api/forehead/fund/recharge/rate — urlForm — STAPI.RechargeRateRequest

參數	型別	必填	說明
coin	string	✅	幣種代碼（如 `"USDT"`）

Response： data 為 Decimal，即時匯率。

USDT 匯率（HttpService）

POST api/forehead/fund/recharge/usdt/rate — POST — HttpService

無參數，靠 Header token/uid 認證。

Response： 原始 JSON Dictionary，含匯率數值。

取得充值運營位圖片

POST api/forehead/system/config/images/query — urlForm — STAPI.RechargeOperatePicRequest

參數	型別	必填	說明
categoryId	string	✅	圖片分類 ID，多個以逗號分隔

Response： data 為 JSON 字串，解析為 RechargeOperateModel 陣列，含 images（URL）、actionContent（跳轉連結）、categoryId。

取得代理充值代碼

POST api/forehead/fund/agency/recharge/getCode — urlForm — STAPI.RechargeCodeRequest

無參數，靠 Header token/uid 認證。

Response： data 為 String?，代理充值代碼。

C2C 充值金額

POST api/forehead/fund/recharge/c2c/amount — POST — HttpService

無參數，靠 Header token/uid 認證。

Response： 原始 JSON Dictionary，含金額相關欄位。

清除充值姓名

POST api/forehead/fund/recharge/clear/name — POST — HttpService

無參數，靠 Header token/uid 認證。

Response： 無 data，僅含 code 和 message。

術語說明

術語	說明
運營位	後台可配置的廣告/活動圖片位，透過 `categoryId` 區分位置（如充值頁頂部 Banner），由 `/system/config/images/query` API 取得
NB（支付）	一種需要用戶輸入姓名和卡號的轉帳支付方式，對應 `needName=true` / `needCardNo=true` 的商戶，View 為 `NBPayWayView`
極速轉卡	`agentType=2` 的充值方式，訂單建立後有 `alertTime` 提醒倒計時，用戶需在限時內完成轉帳

實作重點

金額匹配：固定金額類型從 quickAmount 比對；範圍金額類型遍歷 merchantList 找包含該金額的商戶
快捷金額去重：透過 enumerated().filter 去除重複值並排序
加密貨幣協議：USDT 支援 TRC20/ERC20 等，透過 protocolMap 存儲
金額驗證：先檢查快捷選項，再檢查範圍
直播嵌入：充值頁面可嵌入直播流

錯誤碼速查

錯誤碼	處理
`1`	成功
金額超出限額	前端攔截，Toast 提示最小/最大限額
網路錯誤	錯誤訊息提示
通道維護中	後端返回 message，前端 Toast 顯示，該商戶暫時不可用
帳戶凍結	後端返回 message，前端 Toast 顯示並阻止提交
重複提交	已有進行中訂單時後端拒絕，前端跳轉至充值資訊頁顯示現有訂單
未綁定手機號	前端攔截（`onOff=="1"` 且 `telephone` 為空），彈窗引導綁定
未綁定銀行卡	前端攔截（非隱私模式下 `bankCards` 為空），彈窗引導綁卡
三方創建訂單失敗	第三方支付 URL 未返回，Toast 提示「三方创建订单失败」

充值（開發文檔） ​

架構 ​

相關檔案 ​

API ​

初始化充值 ​

取得快捷充值金額列表 ​

C2C 彈性快捷金額 ​

取得充值支付方式列表 ​

提交充值 ​

校驗充值金額 ​

提交充值訂單（第三方跳轉） ​

充值內部轉帳（內部支付） ​

充值狀態追蹤 ​

充值狀態查詢 ​

確認付款（普通充值） ​

確認付款（C2C） ​

催單（普通充值） ​

催單（C2C） ​

取消充值訂單 ​

匯率與運營 ​

取得 USDT 即時匯率 ​

USDT 匯率（HttpService） ​

取得充值運營位圖片 ​

取得代理充值代碼 ​

C2C 充值金額 ​

清除充值姓名 ​

術語說明 ​

實作重點 ​

錯誤碼速查 ​

充值（開發文檔）

架構

相關檔案

API

初始化充值

取得快捷充值金額列表

C2C 彈性快捷金額

取得充值支付方式列表

提交充值

校驗充值金額

提交充值訂單（第三方跳轉）

充值內部轉帳（內部支付）

充值狀態追蹤

充值狀態查詢

確認付款（普通充值）

確認付款（C2C）

催單（普通充值）

催單（C2C）

取消充值訂單

匯率與運營

取得 USDT 即時匯率

USDT 匯率（HttpService）

取得充值運營位圖片

取得代理充值代碼

C2C 充值金額

清除充值姓名

術語說明

實作重點

錯誤碼速查