GamePP

外部金流架構規劃
YS 開發團隊|2026 年 4 月
規劃中 — 尚未實作

目標

在 gamepp-branch 串接外部金流（首先為 ECPay/綠界 ATM 虛擬帳號），擴展付款管道，同時維持內部金流的穩定性。

外部買單

買家透過 ECPay 虛擬帳號付款，不依賴 EGoPay 體系

外部賣單

幣商使用自己的銀行帳戶收款，脫離 EGoPay 預撥機制

隔離撮合

外部買/賣單可互相撮合，但不可與內部（EGoPay）單交叉撮合

Feature Flag

先做不啟用，所有外部功能以 feature flag 控制，部署後零影響

核心設計：雙池隔離

在 tickets 表新增 source 欄位，將票單分為 internal / external 兩個撮合池，撮合引擎強制驗證買賣雙方 source 必須一致。

雙池隔離架構
Internal / External 撮合池完全隔離，禁止跨池撮合
source說明買單金流賣單金流
internal 現有 EGoPay 體系 EGoPay 虛擬帳號 / 超商 / 固定帳號 EGoPay 預撥
external 外部金流 ECPay 虛擬帳號 幣商自有銀行帳戶

新增 pay_method

pay_method說明source
1 ~ 9現有 EGoPay 各付款方式internal
10ECPay ATM 虛擬帳號external
11外部銀行轉帳（幣商自有帳戶）external

ECPay 買單流程

使用 ECPay 新版 Payment API（JSON + AES），直接取得虛擬帳號，不需導向 ECPay 付款頁面。

ECPay 買單流程
從建單到付款完成的完整流程

ECPay API

環境Endpoint
測試https://ecpayment-stage.ecpay.com.tw/1.0.0/Cashier/GenPaymentCode
正式https://ecpayment.ecpay.com.tw/1.0.0/Cashier/GenPaymentCode

ECPay 回呼

回呼時機關鍵欄位回應
PaymentInfoURL 取號成功 BankCode, vAccount, ExpireDate 1|OK
ReturnURL 付款完成 RtnCode=1, TradeAmt, PaymentDate 1|OK

CheckMacValue 計算

參數按 key 排序 → & 串接 → 前加 HashKey 後加 HashIV → URL encode → 轉小寫 → SHA256 → 轉大寫

外部賣單流程

幣商使用自己的銀行帳戶建立賣單，脫離 EGoPay 預撥機制。賣單建立後進入審核、撮合、撥款流程。

Step 1：建賣單

pay_method=11, source=external
含幣商銀行帳戶資訊

Step 2：審核預撥

驗證幣商已預撥保證金
is_paid 審核通過

Step 3：撮合 + 撥款

與外部買單撮合 → 建 order
買方付款完成後撥款給幣商

自動對帳

決策：使用同一個總站 (HQ)

獨立 HQ（不採用）

  • 開發成本高
  • 維護兩套系統
  • 只為一個對帳任務

同一個 HQ（採用）

  • 複用現有 BankReconcileMiddleware
  • bank_transactions 已支援多銀行
  • auto_banking 可擴充
  • 統一管理、低成本
對帳架構
外部賣單透過 API sync 到 HQ，由 reconcileExternal() 對帳

實作計畫

實作階段
Phase內容影響風險
1 Schema migration + feature flag 零影響（default='internal'） 低
2 Match.php source 驗證 零影響（現有 tickets 全是 internal） 低
3 EcpayService + Model + Config 新檔案，不影響現有 低
4 ECPay callback controller 新路由，不影響現有 低
5 External API 擴充 Feature flag 保護 中
6 外部賣單 + HQ 對帳 Feature flag 保護 中
7 測試站啟用 限定測試站 中

檔案清單

新增（gamepp-branch）

檔案用途
app/Services/EcpayService.phpECPay API（建單、驗簽、AES 加解密）
app/Models/EcpayPaymentM.phpecpay_payments model
app/Models/EcpayLogM.phpecpay_logs model
app/Http/Controllers/Api/EcpayCallbackC.phpECPay 回呼處理
config/ecpay.phpECPay credentials (env-based)

修改（gamepp-branch）

檔案改動
Match.php加 source 一致性驗證
TicketM.php加 source 常數
config/admin.php加 pay_method 10, 11
routes/api.php加 ECPay callback 路由
ExternalTicketC.php允許 pay_method=10，設 source=external
TicketAjaxC.php建單時根據 pay_method 設 source

修改（gamepp-web）

檔案改動
BankReconcileMiddleware.php加 reconcileExternal()
Api\TicketC.phpprepaid 同步接受 source 欄位

Feature Flag 機制

部署即安全

所有外部金流入口以 feature_external_payments flag 保護
部署後 flag=0 → 零影響 → 測試完成後改為 1 啟用

驗證項目

🏧

ECPay 取號

測試帳號建 ATM 虛擬帳號成功

🔄

Callback

模擬 ECPay 回呼，trade_status 正確更新

🔗

外部撮合

外部買賣單可撮合

🚫

跨池阻擋

外部 + 內部撮合被拒絕

💰

HQ 對帳

外部賣單同步 HQ 可對帳

🔒

Flag=0 安全

關閉時所有外部功能不可用