金流設定｜系統共通｜UGOMK 操作手冊

金流設定（系統設定 → 金流設定）

2026-06-30 新增：統一管理所有模組共用的金流方式（電商 / 課程 / 場地 / 訂房 / 美業 / POS）。

為什麼抽出來

過去金流設定（ECPay / LINE Pay 憑證）放在「電商模組 → 付款方式」，但實際很多模組都會用到同一份金流：

電商商城（產品結帳）
課程報名（線上付款報名）
場地預約 / 訂房（押金與全額付款）
美業預約（押金）

把金流設定當電商獨家會誤導客戶以為「沒開電商就不能用金流」。實際上金流憑證屬於整個租戶層級的系統設定，所以抽到「系統設定 → 金流設定」統一管理。

三層金流概念釐清（容易混淆）

層級	對應表	用途	在哪設定
POS 結帳分類	`pos_payment_methods`	餐飲 / 美業 POS 櫃台分類（現金 / 信用卡 / 儲值金）	POS 模組 → 結帳方式
系統金流方式（本頁）	`system_payment_methods`	跨模組共用的 provider 設定（ECPay / LINE Pay credentials）	系統設定 → 金流設定
平台訂閱卡 token	`tenant_payment_methods`	平台 billing 訂閱卡綁定（給 super_admin 用）	我的方案 / 帳單

注意：三層彼此獨立，不互通。本頁只管「系統金流方式」（第二層）。

欄位說明

名稱

顯示給後台管理員看的名稱，例：「綠界正式（信用卡）」、「LINE Pay 沙箱」。

Provider

支援：

LINE Pay — 需填 Channel ID + Channel Secret
綠界 ECPay — 需填 Merchant ID + Hash Key + Hash IV + ChoosePayment
貨到付款 — 無需憑證

可用模組（enabled_modules，2026-06-30 新增）

複選清單，限定此金流 provider 對哪些模組可用：

不勾選任何項 = 全模組可用（向後相容預設值）
勾選特定模組 = 只該模組能用此 provider

範例情境：

某店「電商收款」用綠界正式環境、「課程收款」用沙箱測試 → 建 2 組綠界，一組勾「電商」、一組勾「課程報名」
全租戶共用一組 LINE Pay → 不勾任何，全模組通用

沙箱（Sandbox）

開啟 = 用 provider 的測試環境（不會真實扣款）；關閉 = 正式環境。

注意：正式上線前務必關閉沙箱，並且填妥真實 Merchant ID / Hash Key / Hash IV。

目前模式徽章

正式（綠） — 憑證完整且 sandbox=false
沙箱（橘） — 憑證完整且 sandbox=true
Mock（灰） — 缺關鍵憑證，會 fallback 到 mock 模式（僅用於開發測試，不會真實扣款）

給 ECPay 沙箱開發者

官方測試金鑰（網路公開）：

MerchantID = 2000132
HashKey    = 5294y06JbISpM5x9
HashIV     = v77hoKGq4kWxNNIS

填上 + 勾沙箱即可在 ECPay 沙箱環境跑通整個結帳流程。

各模組怎麼用

電商商城

在「電商 → 結帳設定」選擇要顯示給顧客的金流方式。顧客在結帳頁勾選後，跳轉 ECPay / LINE Pay 完成付款。

課程報名

「課程 → 設定」啟用「線上付款」→ 選一個 provider。學員按報名時若課程收費，會跳金流，付款成功才正式報名。

場地預約 / 訂房 / 活動

到對應模組的「設定」頁啟用付款，選擇 provider。

加新模組要接金流時

開發者請走 lib/payment/methods.ts 的 helper：

import { getPaymentMethodsForTenant } from '../lib/payment/methods';

// 撈該模組可用的金流方式
const list = await getPaymentMethodsForTenant(schema, { module: 'your_module_id' });

詳見專案文件 docs/specs/new-module-checklist.md 「新模組金流接入 SOP」。

舊資料遷移

部署後 boot-mig (F46) 會自動把舊「電商付款方式」(ec_payment_methods) 的資料 copy 到新表 (system_payment_methods)，舊資料不刪（保留 1 sprint，下個 sprint F47 才 DROP）。

舊「電商 → 付款方式」頁面已改成 3 秒 redirect 到本頁。