提款

最後更新：2026-04-09

功能說明

提供使用者從帳戶提取餘額的完整流程。支援多種提款渠道：銀行卡（普通/C2C）、數字貨幣（USDT/TB/TBU/EB）。依商戶開啟的渠道動態顯示可用提款方式，首次使用數字貨幣提款會顯示操作引導。

使用者流程

進入「我的」→ 點擊「提款」→ WithdrawDetailViewController
頁面顯示可用提款方式 Tab（依 WithdrawViewModel.withdrawTypes 決定）
支援的提款類型：
- 銀行卡（.bank）：普通銀行卡 + C2C
- 普通（.normal）：標準銀行卡提款
- C2C（.c2c）：個人對個人轉帳
- 數字貨幣（.digital(type)）：USDT / EB Pay / TB Pay / TBU
選擇提款方式後填寫金額與目標帳號
若有隱私模式且首次提款（isPrivacyUserFirstWithdraw）→ 特殊引導
若有多渠道且含數字貨幣 → 首次顯示操作引導（needShowGuide()）
確認提交 → 依渠道呼叫對應 API

頁面跳轉

「我的」首頁提款按鈕 → WithdrawDetailViewController
數字貨幣新增地址 → BBAddVirtualAddressViewController
虛擬貨幣提款 → BBVirtualWithdrawViewController

技術視角（開發看這裡）

相關檔案

類型	檔案路徑
ViewController（提款詳情）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/C/WithdrawDetailViewController.swift`
ViewModel（提款）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/C/WithdrawViewModel.swift`
ViewController（虛擬提款）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/UserInfo/C/BBVirtualWithdrawViewController.swift`
ViewController（新增虛擬地址）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/UserInfo/C/BBAddVirtualAddressViewController.swift`
ViewController（掃碼）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/UserInfo/C/BBScanViewController.swift`
API（USDT 地址）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/Address/USDT/STAPI+WithdrawalUSDTAddressRequest.swift`
API（TB 地址）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/Address/TB/STAPI+WithdrawalTBAddressRequest.swift`
API（TBU 地址）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/Address/TBU/STAPI+WithdrawalTBUAddressRequest.swift`
API（EB 地址）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/Address/EB/STAPI+WithdrawalEBAddressRequest.swift`
API（加密貨幣排序）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/STAPI+WithdrawalCryptoSortRequest.swift`
API（提款最新狀態）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Withdraw/STAPI+WithdrawLastStatusRequest.swift`
API（提款匯率）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Withdraw/STAPI+WithdrawRateRequest.swift`
API（預約提款配置）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Withdraw/STAPI+ReserveInfoRequest.swift`
API（提款確認到帳）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Withdraw/STAPI+WithdrawSubmitConfirmReceiveRequest.swift`
API（C2C 確認到帳）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Withdraw/STAPI+C2CSubmitConfirmReceiveRequest.swift`
API（C2C 拆單全部確認）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Withdraw/STAPI+C2CSplitSubmitConfirmReceiveAllRequest.swift`
Model（提款資訊）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/M/WithdrawInfoModel.swift`
Model（提款記錄）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/M/WithdrawModel.swift`
Model（提款最新狀態）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/M/WithdrawLastStatusModel.swift`
Model（提款狀態 enum）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/M/WithdrawStatusInput.swift`
View（狀態顏色 enum）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/V/Detail/WithdrawStatusEnums.swift`
View（通道限額顯示）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Withdraw/V/BottomView/WithdrawTypeChannelView.swift`
Service（提交提款）	`/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Helpers/HttpService.swift`
API（銀行卡列表）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/BankCard/STAPI+UserBankCardRequest.swift`
API（支援銀行）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/BankCard/STAPI+SupportBankRequest.swift`
API（新增銀行卡）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/BankCard/STAPI+AddBankCardRequest.swift`
API（刪除銀行卡）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/User/BankCard/STAPI+DeleteBankCardRequest.swift`
API（轉帳資訊）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Transfer/STAPI+TransferInfoRequest.swift`
API（轉帳提交）	`/Users/user/Work/bbsport-new/BBSport/API/STAPI/Transfer/STAPI+TransferSubmitRequest.swift`

API

功能說明	Namespace	Endpoint	Method	主要參數
用戶已綁定銀行卡	STAPI	`api/forehead/fund/userbankcard/list`	POST urlForm	無
支援銀行列表	STAPI	`STAPI+SupportBankRequest`	POST urlForm	無
新增銀行卡	STAPI	`STAPI+AddBankCardRequest`	POST urlForm	無
申請新增銀行卡	STAPI	`STAPI+ApplyAddBankCardRequest`	POST urlForm	需先申請再確認
刪除銀行卡	STAPI	`STAPI+DeleteBankCardRequest`	POST urlForm	無
USDT 地址	STAPI	`STAPI+WithdrawalUSDTAddressRequest`	POST urlForm	無
USDT 協議地址	STAPI	`STAPI+WithdrawalUSDTProtocolAddressRequest`	POST urlForm	TRC20/ERC20 等
TB 地址	STAPI	`STAPI+WithdrawalTBAddressRequest`	POST urlForm	無
TBU 地址	STAPI	`STAPI+WithdrawalTBUAddressRequest`	POST urlForm	無
EB 地址	STAPI	`STAPI+WithdrawalEBAddressRequest`	POST urlForm	無
省份列表	STAPI	`STAPI+ProvinceRequest`	POST urlForm	用於銀行卡地址
加密貨幣提款排序	STAPI	`STAPI+WithdrawalCryptoSortRequest`	POST urlForm	無
提交提款申請	Legacy	`api/forehead/fund/withdraw/submit`	POST urlForm	`amount`, `type`, `cardId`, `orgSubmitType`, `code`（驗證碼）, `durationId`（預約）, `reallyName`; 數字貨幣帶 `usdtId`/`ebId`/`tbId`/`tbuId`
提款最新狀態	STAPI	`api/forehead/fund/withdraw/last/status`	POST urlForm	無（回傳 `WithdrawLastStatusModel`，含進度條 `currentStep`、提款記錄 `withdraws`）
提款資訊（含限額）	Legacy	`api/forehead/fund/withdraw/info/new`	POST urlForm	無（回傳 `WithdrawInfoModel`，含 `generalConfig`/`quickConfig`）
提款是否關閉	Legacy	`api/forehead/fund/withdraw/isClosed`	POST urlForm	無
提款匯率查詢	STAPI	`api/forehead/fund/withdraw/rate`	POST urlForm	`coin`（幣種代碼）
預約提款配置	STAPI	`api/forehead/fund/withdraw/reserve/config/get`	POST urlForm	無（回傳 `AppointmentInfoModel`）
提款訂單確認到帳	STAPI	`api/forehead/fund/withdraw/submit/confirm/receive`	POST urlForm	`orderId`
C2C 訂單確認到帳	STAPI	`api/forehead/fund/c2c/submit/confirm/receive`	POST urlForm	`orderId`
C2C 拆單全部確認到帳	STAPI	`api/forehead/fund/c2c/split/submit/confirm/receive/all`	POST urlForm	`orderId`（parentOrderId）
C2C 確認付款	Legacy	`api/forehead/fund/c2c/submit/confirm/payment`	POST urlForm	—
C2C 催單	Legacy	`api/forehead/fund/c2c/submit/hasten`	POST urlForm	—
C2C 拆單明細	STAPI	`api/forehead/data/balance/load/withdraw/splitOrder`	POST urlForm	—
C2C 彩蛋資訊	STAPI	`api/forehead/fund/c2c/get/egg/info`	POST urlForm	無
提款驗證碼	STAPI	`api/forehead/user/setting/withdraw/validate/get/code`	POST urlForm	無
提款安全驗證碼	STAPI	`api/forehead/user/setting/withdraw/validate/switch/get/code`	POST urlForm	無

金額限制與手續費規則

提款通道分級

系統將提款配置分為兩級通道（WithdrawTypeChannel）：

通道	欄位	說明
普通提現（`.general`）	`generalConfig: GeneralConfig`	標準額度範圍
大額提現（`.quick`）	`quickConfig: GeneralConfig`	更高的上限額度

GeneralConfig 核心欄位

欄位	型別	說明
`minLimit`	Double	最低提款金額（法幣）
`maxLimit`	Double	最高提款金額（法幣）
`usdtMinLimit` / `usdtMaxLimit`	Double	數字幣整體最低/最高限額
`usdtLimits: [UsdtLimitModel]`	Array	按協議（TRC20/ERC20）區分的最低/最高限額
`amountLimit`	Double	提款總額度上限
`leftWithdrawCount`	Int	當日剩餘提款次數
`freeTimes`	Int	當日免手續費次數
`leftFreeCount`	Int	當日剩餘免手續費次數
`feeType`	`WithdrawFeeType`	`.percent`（百分比）或 `.fix`（固定金額）
`fee`	Double	手續費率/固定金額
`feeLimit`	Double	手續費上限（`maxFee`，為 0 表示無上限）

手續費計算邏輯（`getWithDrawFeeAmount`）

若 leftFreeCount > 0 → 手續費 = 0（免費次數未用完）
.percent 模式 → fee = withdrawAmount * fee / 100
.fix 模式 → fee = fee（固定值）
若計算結果 > feeLimit 且 feeLimit != 0 → 封頂為 feeLimit

C2C（專屬提現）限額（`WithdrawSpeedModel`）

欄位	說明
`amountLimit`	當日提現金額上限
`withdrawDailyUseLimit`	當日提現次數上限
`withdrawCount`	總次數
`leftWithdrawCount`	當日剩餘次數
`multiple`	提現流水倍數
`amounts` / `amountTags`	快捷金額選項與對應文案
`withdrawHandlingFeeType`	1=百分比 / 2=固定金額
`withdrawHandlingFeeValue`	手續費費率/金額
`withdrawHandlingFeeMax`	手續費上限
`matchWaitTime`	匹配等待時間

頁面提示文案格式

提款限額為 {minLimit}～{maxLimit}；今日免手續費提現剩餘 {leftFreeCount}/{freeTimes} 次；超過免費次數後，單筆提現手續費 {fee}%/{fee}元。

提款訂單狀態流轉

WithdrawStatusInput（後端完整狀態碼 → 前端 Int enum）

值	狀態碼名稱	前端歸類
-3	風險待審核	處理中
-2	風險審核拒絕	失敗
0	風險審核通過，待出款	處理中
1	已出款 / 提現成功	成功
2	拒絕出款 / 提現失敗	失敗
3	申請退回	處理中
4	拒絕提現，資金已退回	失敗
5	不處理，資金不退回	失敗
6	申請強制成功中	處理中
7	待處理	處理中
8	已強制成功	成功
9	拒絕強制成功	失敗
10	三方自動出款中	處理中（v4.7.6 後不再使用）
11	出款專員處理中	處理中
12	超時未確認	處理中（v4.7.6 後不再使用）
13	部分退回中	處理中（v4.7.6 後不再使用）
14	部分退回成功	成功（v4.7.6 後不再使用）
15	待確認到帳	確認收款
16	待付款	確認收款

WithdrawDisplayStatusInput（展示用狀態，`isC2CSplitWithdrawOpen = true` 時使用）

值	狀態
1	失敗
2	成功
3	已確認
4	處理中
7	確認收款（按鈕）

C2C 拆單狀態分類（v4.7.6）

C2C 拆單（type = 77）：處理中 = -3,6,0,3,7,10,11,13 / 成功 = 1,8 / 確認收款 = 15,16 / 失敗 = -2,5,4,2,9
三方拆單（type = 1）：處理中 = -3,6,0,3,7,10,11 / 成功 = 1,8 / 確認收款 = 處理中且 receivedConfirmDate == null / 已確認 = 處理中且 receivedConfirmDate != null / 失敗 = -2,5,4,2,9

進度條（`WithdrawCurrentStepInput`，對應 `currentStep` 欄位）

申請已提交
等待付款
待確認到帳
提現完成

顏色枚舉（`WRStatus`）

狀態	值	顏色
normal	-2	灰色
fail	-1	紅色
handling	0	藍色
success	1	綠色

流水（打碼量）要求

WithdrawInfoModel.leftAmount：需要完成的剩餘流水金額，若 > 0 表示使用者尚有未完成的流水要求
WithdrawSpeedModel.multiple：C2C 提現的流水倍數（需完成的投注倍數）
funFreezeBalance：娛樂凍結餘額（未達流水的娛樂投注額）
sportFreezeBalance：體育凍結餘額（未達流水的體育投注額）
提示文案：「剩餘娛樂有效投注額 XXX 可享受下次免費大額提現」

法幣 vs 虛擬幣提款差異

項目	法幣（銀行卡 / C2C）	數字貨幣（USDT/TB/TBU/EB）
限額來源	`generalConfig.minLimit` / `maxLimit`	`generalConfig.usdtMinLimit` / `usdtMaxLimit` 或依協議從 `usdtLimits` 取
判斷用 flag	`isUseBankLimit = true`	`isUseBankLimit = false`
匯率	不適用	各幣種獨立匯率（`usdtWithdrawRate` / `ebWithdrawRate` / `tbWithdrawRate` / `tbuWithdrawRate`），精度 USDT/TB/TBU = 4 位、EB = 2 位
匯率 API	—	`api/forehead/fund/withdraw/rate`，參數 `coin`
地址管理頁面	銀行卡列表	`BBVirtualWithdrawViewController`（管理錢包地址）
地址上限	—	每種幣最多 5 個地址（`addressMaxCount = 5`）
協議支援	—	USDT: TRC20/ERC20 等；TB/TBU 有 `tbProtocols`/`tbuProtocols`；EB 無協議區分
提交時參數差異	`cardId`	`usdtId` / `ebId` / `tbId` / `tbuId`（由 `digitalType.withdrawSubmitIdKey` 決定）
地址排序 API	—	`STAPI.WithdrawalCryptoSortRequest` 決定顯示順序

資料模型

WithdrawInfoModel

欄位	說明
`name`	用戶姓名（隱私模式下可能為空）
`withdrawSwitch`	可用提款方式陣列（`[WithdrawSwitchModel]`）
`isOpenBankCardWithdraw`	是否開放銀行卡提款
`isOpenC2CWithdraw`	是否開放 C2C 提款
`isShowDigitalWithdrawOpen`	是否開放數字貨幣提款

WithdrawType（提款類型枚舉）

類型	說明
`.bank`	銀行卡（含 C2C）
`.normal`	標準銀行卡
`.c2c`	C2C 個人轉帳
`.digital(.usdt)`	USDT
`.digital(.ebPay)`	EB Pay（網銀）
`.digital(.tbPay)`	TB Pay（泰銀）
`.digital(.tbu)`	TBU（泰銀升級版）
`.unknown`	未知（後端新增但前端未實作）

實作重點

提款類型配置邏輯（configureWithdrawTypes）：
- 遍歷 withdrawSwitch（後端設定），過濾 status == "1" 的啟用項
- 依前端開關（isOpenBankCardWithdraw 等）再次過濾
- 數字貨幣 Tab 固定在最後：若存在 .digital(.usdt) 移至陣列末尾
數字貨幣引導顯示（needShowGuide()）：
- 已完成引導（isDigitalGuideFinished UserDefaults = true）→ 不顯示
- 只有一種提款渠道 → 不顯示
- 沒有數字貨幣渠道 → 不顯示
隱私模式首次提款（isPrivacyUserFirstWithdraw）：
- 隱私模式開啟（IFUserModel.privacyMode == true）且 withdrawInfoModel.name 為空
- → 需引導使用者先設定真實姓名
銀行卡狀態：status == 2 表示人工審核中，此時不可使用該卡提款
已知限制：WithdrawType 中的 .unknown case 用於處理後端未來可能新增的類型，前端目前不處理

API 呼叫流程

進入提款頁面 (WithdrawViewController)

viewWillAppear → refreshWithdrawInfo()
  ├─ [API 1] POST api/forehead/fund/withdraw/info/new
  │  → 提款設定、支援方式、限額
  │
  ├─ [API 2] POST api/forehead/fund/withdraw/usdt/rate
  │  → USDT 即時匯率
  │
  ├─ [API 3] POST api/forehead/fund/withdraw/reserve/config/get
  │  → 預約提款時段
  │
  └─ [API 4] POST api/forehead/gamebet/transfer/info
     → 中心錢包餘額

載入銀行卡 / 虛擬幣地址

withdrawInfo 回調後:
  ├─ [API] POST api/forehead/fund/userbankcard/list → 綁定銀行卡
  │
  └─ [並行] 各幣種地址
     ├─ POST api/forehead/fund/user/usdt/list
     ├─ POST api/forehead/fund/user/tb/list
     ├─ POST api/forehead/fund/user/eb/list
     └─ POST api/forehead/fund/user/tbu/list

提交提款

用戶填寫金額 → confirmBtnClick()
  ├─ [API 1] POST api/forehead/user/setting/withdraw/validate/get/code
  │  {type:"cash", lotNumber, captchaOutput, passToken, genTime}
  │  → 發送驗證碼
  │
  ├─ 用戶輸入驗證碼
  │
  ├─ [API 2] POST api/forehead/fund/withdraw/submit
  │  {amount, type, code, cardId/usdtWithdrawAddressId/..., orgSubmitType, durationId?}
  │
  └─ 成功後
     └─ [API 3] POST api/forehead/fund/withdraw/last/status → 取得新訂單

提款狀態 (WithdrawDetailViewController)

[API] POST api/forehead/fund/withdraw/last/status → 查詢最新狀態

確認收款:
  ├─ 普通: POST api/forehead/fund/withdraw/submit/confirm/receive {orderId}
  ├─ C2C:  POST api/forehead/fund/c2c/submit/confirm/receive {orderId}
  └─ C2C拆單: POST api/forehead/fund/c2c/split/submit/confirm/receive/all {parentOrderId}

管理銀行卡

新增: POST api/forehead/fund/userbankcard/v2/bindcard {name, bankId, cardNo, code}
  └─ 失敗 → POST api/forehead/fund/userbankcard/v2/apply/bindcard (人工綁卡)
刪除: POST api/forehead/fund/userbankcard/delete {cardId, code}
支援列表: POST api/forehead/fund/userbankcard/supportBankList

管理虛擬幣地址 (USDT 為例)

協議列表: POST api/forehead/fund/user/usdt/protocol/list
取得驗證碼: POST api/forehead/user/setting/binding/usdt/address/get/code/v2
新增: POST api/forehead/fund/user/usdt/add {nickName, protocol, address, code}
刪除: POST api/forehead/fund/user/usdt/del {id, code}
(TB/EB/TBU 同結構，替換路徑中幣種即可)

提款 ​

功能說明 ​

使用者流程 ​

頁面跳轉 ​

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

相關檔案 ​

API ​

金額限制與手續費規則 ​

提款通道分級 ​

GeneralConfig 核心欄位 ​

手續費計算邏輯（getWithDrawFeeAmount） ​

C2C（專屬提現）限額（WithdrawSpeedModel） ​

頁面提示文案格式 ​

提款訂單狀態流轉 ​

WithdrawStatusInput（後端完整狀態碼 → 前端 Int enum） ​

WithdrawDisplayStatusInput（展示用狀態，isC2CSplitWithdrawOpen = true 時使用） ​

C2C 拆單狀態分類（v4.7.6） ​

進度條（WithdrawCurrentStepInput，對應 currentStep 欄位） ​

顏色枚舉（WRStatus） ​

流水（打碼量）要求 ​

法幣 vs 虛擬幣提款差異 ​

資料模型 ​

WithdrawInfoModel ​

WithdrawType（提款類型枚舉） ​

實作重點 ​

API 呼叫流程 ​

進入提款頁面 (WithdrawViewController) ​

載入銀行卡 / 虛擬幣地址 ​

提交提款 ​

提款狀態 (WithdrawDetailViewController) ​

管理銀行卡 ​

管理虛擬幣地址 (USDT 為例) ​

提款

功能說明

使用者流程

頁面跳轉

技術視角（開發看這裡）

相關檔案

API

金額限制與手續費規則

提款通道分級

GeneralConfig 核心欄位

手續費計算邏輯（`getWithDrawFeeAmount`）

C2C（專屬提現）限額（`WithdrawSpeedModel`）

頁面提示文案格式

提款訂單狀態流轉

WithdrawStatusInput（後端完整狀態碼 → 前端 Int enum）

WithdrawDisplayStatusInput（展示用狀態，`isC2CSplitWithdrawOpen = true` 時使用）

C2C 拆單狀態分類（v4.7.6）

進度條（`WithdrawCurrentStepInput`，對應 `currentStep` 欄位）

顏色枚舉（`WRStatus`）

流水（打碼量）要求

法幣 vs 虛擬幣提款差異

資料模型

WithdrawInfoModel

WithdrawType（提款類型枚舉）

實作重點

API 呼叫流程

進入提款頁面 (WithdrawViewController)

載入銀行卡 / 虛擬幣地址

提交提款

提款狀態 (WithdrawDetailViewController)

管理銀行卡

管理虛擬幣地址 (USDT 為例)