本章目標

上一章完成了營隊梯次、名額、候補與後台。本章沿用相同專案，加入台灣業者常見的三個營運環節：

• 透過綠界測試環境建立付款交易。
• 由可信任的後端通知更新訂單，而不是相信前端成功頁。
• 透過 LINE Messaging API 或 Email 發送付款與行前通知。
• 提供工作人員可查核的訂單、付款嘗試與通知紀錄。

完成後，家長會從報名進入待付款，付款成功才占用正式名額；工作人員能看出「已付款但通知失敗」和「尚未付款」是兩種不同問題。

為什麼這一章重要

對小型營隊而言，付款往往仍靠轉帳末五碼與人工對帳。改成線上金流能減少工作，但也帶來新的失敗狀態：使用者付完款卻關掉頁面、付款服務重複通知、前端被竄改金額、通知訊息發送失敗，甚至測試與正式商店代號混用。

真正可靠的付款流程不是「按下按鈕後跳到成功頁」，而是：

報名 -> 建立待付款訂單 -> 導向付款頁
     -> 綠界後端通知 -> 驗證簽章與金額
     -> 訂單已付款 -> 報名狀態更新 -> 發送通知

其中任何一步都可能重試。系統必須允許重試，但不能重複收款、重複建立名額或重複發送十次通知。

思考模型：付款、報名與通知是三套狀態

不要用單一 status 表示所有事情。至少分成：

• 報名：pending/confirmed/waitlisted/cancelled。
• 訂單：unpaid/processing/paid/failed/refunded/expired。
• 通知：queued/sent/failed/skipped。

「訂單已付款」不代表 LINE 一定送達；「LINE 失敗」也不可以把付款改回失敗。把狀態拆開，客服才能知道該補發通知、重新對帳，還是聯絡家長。

開始之前

先完成第 22 章，並準備：

• 綠界測試環境的商店資訊。
• LINE Official Account 與 Messaging API channel；若尚未申請，可先使用 mock endpoint 驗證通知佇列。
• 後端 secrets 管理能力。
• 一個可由外部服務連線的 HTTPS callback URL。

商店代號、HashKey、HashIV、LINE channel access token 都不能寫在前端、提示詞輸出畫面或 Git 儲存庫。正式上線前，必須重新核對綠界最新 API 文件、商家資格、費率與回傳規格。

步驟 1：把價格固定在後端

在 sessions 或價格方案表保存新台幣整數金額。建立訂單時，後端依 session_id 讀取價格，不能接受瀏覽器傳入的最終金額。

新增資料：

• orders：registration_id、order_number、amount_twd、status、payment_deadline。
• payment_attempts：order_id、provider、provider transaction ID、請求時間、回傳時間、驗證結果與安全摘要。
• payment_events：事件類型、provider event ID、收到時間、處理結果。

一筆報名可以有多次付款嘗試，但同一時間只能有一筆有效待付款訂單。訂單編號由後端產生並設唯一限制。

步驟 2：規劃付款與名額保留

本案例採「短時間保留名額」：建立訂單後保留 30 分鐘，逾時未付款則釋放，家長需要重新確認是否仍有名額。這個策略比無限期占位公平，也比「先付款、再發現額滿退款」容易理解。

Plan Mode 提示詞：

請在現有營隊報名專案規劃綠界付款，不要先改程式。
報名建立後產生新台幣訂單並保留名額 30 分鐘。價格只能由後端依梯次讀取，前端不可指定金額。
付款、報名與通知要使用獨立狀態。綠界付款結果必須經後端 callback 驗證簽章、商店代號、訂單編號與金額，並可安全處理重複通知。
請列出資料表、狀態轉換、Edge Function、secrets、逾時釋放、人工對帳與完整失敗情境。先使用測試環境，不要加入正式憑證。

步驟 3：由 Edge Function 建立交易

建立 create-payment Edge Function：

1. 驗證登入者有權為該報名付款。
2. 重新檢查梯次、報名與保留期限。
3. 從資料庫讀取價格並建立訂單。
4. 依綠界最新版規格產生交易欄位與 CheckMacValue。
5. 回傳付款頁所需資料或導轉資訊。

只把完成導轉需要的欄位傳回瀏覽器，不回傳 HashKey、HashIV 或 channel token。函式日誌也要遮蔽 secrets 與個資。

Build Mode 提示詞：

請實作 create-payment Edge Function 與付款按鈕。
後端必須驗證目前使用者、registration ownership、訂單狀態與付款期限，並從 sessions 讀取 amount_twd。
使用 secrets 取得綠界測試商店設定，依官方規格產生 CheckMacValue。不要接受前端傳入的價格，不要記錄 HashKey、HashIV 或完整個資。
重複點擊付款按鈕時重用仍有效的待付款訂單，不要建立多筆有效訂單。
付款頁返回後先顯示「正在確認付款結果」，不可直接標示已付款。

先用不會扣款的測試示範驗收畫面與狀態拆分。訂單顯示 Sandbox、新台幣 6,800 元、後端決定金額與 30 分鐘名額保留，避免測試人員把它誤認為正式金流。

圖 23-1：付款測試頁明確標示 Sandbox，金額與訂單資訊不可由前端任意修改。

步驟 4：分清 ReturnURL 與前端導回頁

瀏覽器回到網站只能代表使用者完成或離開付款介面，不能作為入帳證據。可信任的付款結果來自綠界送到後端的 callback。

payment-callback 必須：

1. 解析原始回傳欄位。
2. 依官方規格驗證 CheckMacValue。
3. 比對商店代號、訂單編號與後端保存的金額。
4. 以 provider transaction ID 或事件唯一鍵防止重複處理。
5. 在交易中將訂單改成 paid，再更新報名狀態。
6. 建立通知工作，而不是在付款交易中等待 LINE 回應。
7. 回傳 provider 要求的確認格式。

錯誤簽章、未知訂單或金額不符必須記錄安全事件並拒絕更新。不要為了「讓測試先過」而跳過驗章。

步驟 5：建立付款確認頁

家長回到網站後，確認頁使用訂單編號向自己的後端查詢狀態：

• processing：顯示正在確認並短時間輪詢。
• paid：顯示付款完成、梯次與行前資訊。
• failed：提供重新付款或聯絡方式。
• expired：說明名額已釋放，回到梯次頁重新確認。

確認頁不接受網址參數 status=paid 作為真相，也不能讓使用者查詢別人的訂單。

圖 23-2：模擬瀏覽器先返回時，只能進入 processing，不能直接宣告付款成功。

只有模擬已驗證的後端 callback 後，畫面才顯示已付款，通知狀態則獨立顯示為 sent。重複 callback 由事件唯一鍵去重，不會重複入帳或通知。

圖 23-3：付款與通知是兩套狀態；本例為 paid 加 sent。

步驟 6：連結 LINE 使用者

LINE Messaging API 的 push message 需要可接收訊息的 user ID。實務上可用 LINE Login 並把 LINE Official Account 放在同一 provider 下，讓使用者登入／授權後建立 line_links。不要假設只知道手機號碼就能推播 LINE。

line_links 保存 app user ID、LINE user ID、連結與解除時間。畫面要說明用途，並允許使用者解除。使用者未加好友、封鎖帳號或訊息額度不足時，推播可能無法送達，因此 Email 或後台待辦仍然必要。

步驟 7：用通知佇列隔離外部失敗

新增 notification_deliveries：

• recipient_user_id、channel、template_key。
• related_type、related_id。
• status、attempt_count、next_attempt_at。
• provider_message_id、last_error_code。

付款成功交易只新增一筆 queued 工作。背景工作再呼叫 LINE 或 Email。使用由 template_key + related_id + recipient 組成的唯一鍵，避免 callback 重送時重複通知。

訊息只放必要資訊，例如課程、梯次、付款完成與報名編號。不要在 LINE 推播兒童備註或其他敏感資料。

請新增付款成功通知工作流。
付款 callback 成功後只建立 queued notification，不要在同一資料庫交易中等待 LINE API。
若使用者有有效 line_link，透過 LINE Messaging API 發送；否則改送 Email。
同一訂單、同一範本、同一收件者只能有一筆有效通知。失敗時保存安全的錯誤碼並採有限次數退避重試，永久失敗要出現在工作人員待辦。
訊息不可包含學員備註、完整地址或其他非必要個資。

步驟 8：建立行前提醒

付款完成後可以排定開課前 7 天與前 1 天提醒。排程依 Asia/Taipei 計算，並在每次發送前重新確認：

• 報名仍有效。
• 梯次沒有取消或改期。
• 這個範本尚未成功發送。
• 使用者仍同意該通知通道。

梯次改期時不要只改日期。建立 session_events，標記原日期、新日期與通知狀態，讓工作人員能追蹤哪些家長已收到變更通知。

步驟 9：建立對帳後台

後台把問題分成四個佇列：

• 待付款且即將逾時。
• provider 顯示成功但本地尚未入帳，需要查核。
• 本地已付款但通知失敗。
• 退款或取消需要人工處理。

每筆訂單顯示報名編號、金額、建立時間、付款狀態、最近事件與通知狀態。敏感 request payload 只保存必要摘要；完整秘密或卡片資料不能進資料庫。

人工修正必須要求原因、記錄操作者與前後狀態。不要提供一顆沒有確認步驟的「改成已付款」按鈕。

圖 23-4：對帳後台把四種需人工介入的問題分開，並避免顯示 secrets、卡號與兒童個資。

步驟 10：測試失敗而不只是成功

在測試環境驗證：

1. 正常付款後，callback 將訂單改為 paid，報名確認且只通知一次。
2. 瀏覽器先回站、callback 尚未到達時顯示 processing。
3. 同一 callback 傳送三次，只處理一次。
4. CheckMacValue 錯誤時拒絕更新並記錄事件。
5. 回傳金額與訂單金額不同時拒絕更新。
6. 付款按鈕重複點擊不建立多筆有效訂單。
7. 訂單逾時後釋放名額；遲到的成功通知進入人工查核，不自行搶回已給別人的名額。
8. LINE 被封鎖或 API 逾時時，付款仍保持成功並產生通知待辦。
9. 使用者無法查詢其他人的訂單。
10. 測試與正式 secrets 不會混用。

驗證提示詞：

請對營隊付款與通知流程做端到端驗證。
使用綠界測試環境，測試正常付款、前端先返回、重複 callback、錯誤 CheckMacValue、金額不符、訂單逾時與付款按鈕重複點擊。
再模擬 LINE API timeout、使用者未綁定 LINE 和訊息永久失敗。
確認付款、報名與通知狀態互不污染，且每個測試列出輸入、實際資料庫狀態、畫面結果、事件紀錄與是否通過。
不要為了通過測試停用簽章驗證或權限規則。

實作練習

為「暑期 Python 冒險營 A 梯」設定 6,800 元與 30 分鐘付款期限，建立以下四筆測試：

• 家長 A 正常付款並已綁 LINE。
• 家長 B 正常付款但未綁 LINE，改寄 Email。
• 家長 C 付款 callback 被重送三次。
• 家長 D 訂單逾時後才收到成功通知。

預期結果是 A、B、C 各只有一筆 paid 訂單與一次有效通知；D 不會自動占用已釋放的名額，而是進入人工查核。對帳後台能清楚說明每一筆為什麼處於目前狀態。

常見錯誤

相信前端成功頁

使用者可以修改網址，也可能在 callback 到達前先返回。只有驗證過的後端通知能改變付款狀態。

由前端傳金額

前端只能傳梯次或訂單識別碼，金額必須由後端保存的價格計算。

把 secrets 寫進程式碼

商店金鑰與 LINE token 應放在後端 secrets，日誌和錯誤訊息也不能輸出。

callback 沒有冪等

外部服務可能重送。每個 provider event 或 transaction ID 必須有唯一防護。

使用 LINE Notify 舊教學

本書採 LINE Messaging API。不要依賴已終止的 LINE Notify 流程。

通知失敗就回滾付款

通知是後續工作。付款成功必須保留，通知另行重試或人工處理。

上線前檢查清單

• [ ] 價格由後端讀取並使用新台幣整數。
• [ ] 測試與正式商店設定完全分離。
• [ ] CheckMacValue、訂單、商店與金額均已驗證。
• [ ] callback 重送不會重複入帳或通知。
• [ ] 前端返回頁不直接改成 paid。
• [ ] 名額保留與逾時釋放規則已測試。
• [ ] LINE user ID 經過明確帳號連結取得。
• [ ] 通知失敗不影響付款狀態。
• [ ] 對帳與人工修正都有事件紀錄。
• [ ] 日誌、資料庫與前端均沒有 secrets 或卡片資料。
• [ ] 退款、取消與客服聯絡方式已寫清楚。
• [ ] 正式上線前已核對綠界與 LINE 最新官方文件及費率。

延伸閱讀

• 綠界全方位金流 API 技術文件
• LINE Messaging API：傳送訊息
• LINE Messaging API：接收 webhook
• LINE Login：開始使用
• Lovable integrations

名詞解釋與延伸提問

• Callback／Webhook：外部服務主動呼叫你的後端，通知事件結果。
• CheckMacValue：綠界用來驗證參數完整性的檢查值；產生與驗證方式以最新版官方規格為準。
• 對帳：比較 provider 與本地訂單紀錄，找出漏單、重複或狀態不一致。
• 退避重試：失敗後逐次延長等待時間再重試，避免持續轟炸外部服務。

你可以接著問 Lovable：「請依我的付款期限、退款規則與 LINE 通知範本，產生一份正式上線前的故障演練清單。」下一章會換到診所預約，重點從金流轉向時段競爭、櫃檯操作與敏感資料邊界。

嗨！我是 Wolke，曾任 Google Developer Expert（GDE，2019–2023） 與 LINE API Expert。我熱衷於研究 AI Agent、n8n 自動化工作流及全端開發架構，致力於將 AI 技術轉化為實際的生產力工具。

如果你喜歡這篇文章，歡迎透過以下方式與我交流，獲取更多技術實戰內容：

📚 技術著作：《實用的 Gemini API 開發點子書》，帶你運用 Gemini App、Google AI Studio、Gemini CLI 與 Antigravity IDE，打造 AI Agent 與實用產品。

📝 技術部落格：歡迎追蹤我的 Medium，我會持續分享 Agentic Automation、架構設計與實際開發的踩坑心得。

🎤 技術講座：我持續受邀至技術社群及研討會，分享 AI Agent、自動化工作流、DevOps 與全端開發實戰。曾於 2026 年 6 月 26 日的 DevOpsDays Taipei 2026 主講「不再只是寫腳本！讓 AI 代理人成為你的 SRE 最佳夥伴」工作坊。

如果你的企業、社群或學校正在尋找相關主題講者，歡迎私訊與我聯繫、洽談講座合作！

🎁 免費送 Lovable 額度給讀者！

我每個月會開放 10 個名額，每人 50 點 Lovable 額度，讓大家實際動手打造自己的網站或 App。

參加方式：

1. 訂閱本系列文章
2. 分享任一篇系列文章
3. 私訊分享截圖及你的 Lovable 帳號 Email

確認後，我會邀請你加入 Lovable workspace 並設定 50 點額度。名額有限，送完為止！