# 綠界科技 ECPay 金流(AioCheckOut V5)

## 運作方式
- 學員按「立即購買」→ 系統建立 `pending` 訂單(金額為當下 `currentPrice()` 的快照)→ 自動送出表單到綠界付款頁。
- **只有綠界以 ReturnURL 傳來、且 CheckMacValue 驗證通過的伺服器通知,才會把訂單標記為已付款並開通課程。** 瀏覽器返回頁(`/orders/{order_no}/result`)只顯示狀態,並自動輪詢直到通知到達。
- ATM / 超商是非同步付款:PaymentInfoURL 只儲存繳費資訊(訂單維持 pending),付款成功才由 ReturnURL 通知。
- 未設定金流時:`local` / `testing` 環境維持「按購買就開通」的測試模式;**其他環境(正式)禁止購買付費課程**並顯示「金流尚未設定」。免費課程不經金流。
- 退款、發票、補單不在系統內處理,請到綠界後台操作。管理者無法在系統內把 pending 改成 paid。

## 取得特店資料
- 測試:綠界「測試環境」特店(綠界開發者網站 developers.ecpay.com.tw 的「測試資料」頁提供公開的測試 MerchantID / HashKey / HashIV)。測試後台 https://vendor-stage.ecpay.com.tw 。
- 正式:向綠界申請特店並完成審核後,於廠商後台(https://vendor.ecpay.com.tw)「系統開發管理 → 系統介接設定」取得 MerchantID、HashKey、HashIV。

## 設定方式(二擇一,後台設定優先)
1. **後台**:管理後台 →「金流設定」。HashKey / HashIV 以 APP_KEY 加密存放,儲存後不會再顯示;欄位留空 = 保留原值。切換到正式環境需勾選確認並輸入 `production`。(更換 APP_KEY 後,後台儲存的金鑰會無法解密,需重新輸入。)
2. **.env**:`ECPAY_MERCHANT_ID`、`ECPAY_HASH_KEY`、`ECPAY_HASH_IV`、`ECPAY_ENV=stage|production`。修改後執行 `php artisan config:clear`(若有快取設定)。

用 `php artisan ecpay:check` 檢查設定與列出回呼網址(不會印出金鑰)。

## 回呼網址(必須是外部可連線的 HTTPS)
- ReturnURL:`https://你的網域/payments/ecpay/return`
- PaymentInfoURL:`https://你的網域/payments/ecpay/info`
- 這兩個路由公開、不經登入、排除 CSRF,但一律驗證 CheckMacValue、MerchantID、訂單與金額。
- 本機測試:綠界無法連到 localhost,需用隧道工具(ngrok、cloudflared 等)取得公開 HTTPS 網址並設為 `APP_URL`。若綠界後台有網址白名單設定,請加入你的網域。

## 在測試環境驗證一筆完整交易
1. 設定測試特店資料,`ECPAY_ENV=stage`,確認 `ecpay:check` 沒有 FAIL。
2. 以學員登入購買付費課程,在綠界測試付款頁選信用卡(測試卡號見綠界測試資料頁)或 ATM/超商取號。
3. 到綠界測試廠商後台「訂單查詢」找到該筆交易,使用「模擬付款」,綠界會對 ReturnURL 送出通知(`SimulatePaid=1`)。
4. 確認:訂單頁變成已付款、課程已開通、後台訂單詳情的事件時間軸出現 `paid`。
5. 這一步同時驗證 CheckMacValue 演算法;**簽章必須用真實的綠界測試交易驗證過才能上線**。
- 正式環境(`production`)收到 `SimulatePaid=1` 的通知一律不開通。

## 付款方式
後台可勾選開放的方式(信用卡、網路 ATM、ATM 虛擬帳號、超商代碼、超商條碼)。全選 = `ChoosePayment=ALL`;只選一項 = 直接指定;其餘 = `ALL` 加 `IgnorePayment`(以 `#` 連接排除項)。請在綠界測試環境確認 `IgnorePayment` 的行為符合預期。

## 訂單與排程
- 訂單有效 192 小時(`ECPAY_ORDER_TTL_HOURS`,需大於 ATM 3 天、超商 7 天)。`orders:expire` 每小時把到期 pending 訂單標為 expired(需啟用 Laravel 排程:`* * * * * php artisan schedule:run`)。
- 重新付款會產生新的 MerchantTradeNo,舊的待付款訂單作廢;若舊訂單之後仍收到有效的付款通知,仍會開通(並記錄 `paid_after_expiry`),避免已扣款卻沒課程。已取得 ATM/超商繳費資訊的訂單不會重送。
- 每次回呼原文存於 `order_events`(僅管理員可在訂單詳情查看),不含 HashKey/HashIV。

## 上線檢查表
- [ ] 正式特店資料已填入,環境切為 production,`ecpay:check` 全部 OK
- [ ] 網站為 HTTPS,ReturnURL / PaymentInfoURL 可從外部連線(含防火牆、WAF 不擋綠界)
- [ ] 已在 stage 用「模擬付款」完成完整交易,並用真實信用卡小額測試(正式環境)後於綠界後台退款
- [ ] 排程 `schedule:run` 已啟用
- [ ] 確認 APP_ENV=production,且沒有設定 `ACADEMY_PAYMENT_TEST_MODE=true`
- [ ] 備份 APP_KEY(遺失後無法解密後台儲存的金鑰)
