| name | omg-payment |
| description | Assist non-technical Taiwan merchants in integrating the OMG (歐買尬 / MacroWell OMG)
payment gateway end-to-end via a single natural-language instruction. Triggers when
the user mentions: OMG, 歐買尬, MacroWell, omgpay, 金流串接, 收款, 線上付款, 刷卡串接,
ATM 收款, 超商付款, 退款, 對帳, 儀表板監控, Telegram 付款通知, Discord 付款通知,
or asks to "整合歐買尬金流", "建置金流系統", "建置付款後台儀表板", or "建置付款通知機器人".
Default behavior: full-stack integration including backend, admin dashboard, health
monitoring, Telegram/Discord notification bots, and Taiwan regulatory disclosure
templates, executed as a single automated workflow.
|
| version | 2.0.0 |
| license | MIT |
OMG Payment Skill（歐買尬金流整合指引）
聲明（AI 必讀）：本 Skill 是個人社群專案（非官方），不是 OMG 的官方資源，也未取得任何官方背書。本 Skill 的架構參考自綠界科技的 ECPay-API-Skill，在此致謝。
官方資源優先原則：當本 Skill 內容與官方文件不一致時，AI 必須以官方文件為準，並於回應使用者時明確指出差異。官方來源如下：
AI 於處理 API endpoint、欄位名稱、錯誤代碼、host 位址等精確規格時，應建議使用者前往上述官方來源交叉驗證；不得基於本 Skill 之內容宣稱為官方規格。
歐買尬（OMG）與歐付寶（OPay）為兩家獨立公司，舊版技術資料常將兩者混用。本 Skill 所有範例與 host 參數均指向歐買尬。若使用者提供之內容出現「歐付寶 / opay.tw / opaygo」等字樣，AI 必須主動提醒使用者兩家公司不同，並確認其欲整合之對象後再繼續作業。
整合流程由 AI 助手依據本文件描述之順序自動執行，使用者以自然語言觸發並提供基本商家資訊即可完成整合。
設計原則（AI 必讀）
AI 產出的任何檔案、說明、指令、錯誤訊息，均必須符合下列上手標準：
- 使用者複製 repo 後，依指示執行不超過 5 個終端指令即可啟動完整系統
- 所有設定集中於單一
.env 檔，.env.example 必須逐欄位附註說明與預設值
- 預設資料庫為 SQLite（單檔、無需額外安裝），可視需求切換至 PostgreSQL
- 啟動指令於 macOS、Windows、Linux 均可通用
- 所有錯誤訊息以繁體中文呈現，並附具體修復建議
- Bot 綁定、儀表板開啟、退款執行等操作均提供一行式指令或單一按鈕
- 技術名詞於首次出現時以一句話解釋
- 從 clone 到測試付款成功之完整路徑須能於 30 分鐘內完成
本原則適用於所有 guides、references、commands、templates、scripts 內容。技術規格語氣不等同於「讀者必須自行補齊底層細節」：用詞嚴謹、流程清楚、步驟可複製，這三者同時成立。
§0 AI 執行規則
本節定義 AI 助手在觸發本 Skill 後必須遵循的執行規則。
§0.1 觸發與 onboarding
當使用者發出整合歐買尬金流之相關指令時，AI 必須優先執行 onboarding 流程，不得直接進入技術細節。Onboarding 流程以四個問題組成，AI 應以中文一次性呈現所有問題，由使用者一次回答：
- Q1 — 商品類型：實體商品 / 數位下載 / 線上課程 / 訂閱服務 / 票券或 voucher / 其他
- Q2 — 目標環境：測試環境 / 正式環境 / 兩者（預設）
- Q3 — 附加元件：管理儀表板、健康監控、Telegram 通知機器人、Discord 通知機器人（預設全部包含）
- Q4 — 法規揭露範例：服務條款、隱私權政策、退貨退款政策、首頁與頁尾必要揭露、商品頁必要揭露（預設全部包含）
若使用者以「全部」、「皆需要」、「依預設」等語意回答，AI 應直接套用預設值並進入執行階段，不得繼續追問細節。詳細流程定義於 guides/00-onboarding.md。
§0.2 變數收集
在 onboarding 與後續執行過程中，AI 應以 {{變數名}} 佔位符記錄下列變數，並於執行完成前一次性請使用者補齊：
{{商家名}} {{統一編號}} {{負責人}}
{{客服Email}} {{客服電話}} {{營業地址}}
{{網站網址}} {{商品類型描述}} {{履約保證機制}}
{{猶豫期適用範圍}} {{OMG_MERCHANT_ID}}
{{OMG_HASH_KEY}} {{OMG_HASH_IV}}
{{OMG_API_HOST_STAGE}} {{OMG_API_HOST_PROD}}
{{ADMIN_TOKEN}} {{TG_BOT_TOKEN}}
{{DISCORD_BOT_TOKEN}}
AI 不得在 onboarding 階段逐一詢問變數，以避免打斷使用者思路。所有變數應於執行末端統一收集。
§0.3 執行順序
當 onboarding 完成並進入全自動整合模式時，AI 應依下列順序執行：
- 產生
.env.example，包含 OMG 金鑰、資料庫連線、admin token、bot token 等必要欄位
- 產生後端 webhook 接收器（預設 FastAPI，可依使用者需求改為 Express 或 Laravel）— 參考
guides/02-backend-fastapi.md
- 產生 SHA256 CheckMacValue 輔助函式 — 參考
references/check-mac-value.md
- 產生 race-safe webhook handler — 參考
guides/05-webhook-idempotency.md
- 產生 admin 介面 endpoint（訂單列表、訂單明細、退款、健康摘要）
- 產生測試環境儀表板 — 參考
guides/06-test-dashboard.md
- 產生正式環境儀表板（唯讀探測模式）— 參考
guides/07-prod-dashboard.md
- 產生 Telegram bot — 參考
guides/08-telegram-bot.md
- 產生 Discord bot — 參考
guides/09-discord-bot.md
- 產生退款安全機制 — 參考
guides/10-refund-safety.md
- 產生首頁、頁尾、商品頁之必要揭露區塊 — 參考
guides/11-merchant-homepage.md 與 guides/12-product-page.md
- 產生服務條款、隱私權政策、退貨退款政策之公版範例 — 參考
guides/13-legal-tos.md、guides/14-legal-privacy.md、guides/15-legal-refund.md
- 收集變數並一次性替換所有佔位符
- 執行測試環境儀表板之完整鏈路驗證（create_order → MAC 驗證 → HTTP POST → query_order → refund 簽名），確認全部通過
- （預設執行）商家網站 AI 最佳化 — 參考
guides/18-merchant-ai-optimization.md：為使用者網站產出 llms.txt、llms-full.txt、robots.txt 追加段落、首頁 JSON-LD 結構化資料、頁尾 OMG 使用標註 HTML；模板取自 templates/merchant-llms-txt/
- （預設執行）商家 UI/UX 無障礙檢查 — 參考
guides/19-wcag-ui-ux.md：對於 AI 產出的商家前台程式碼，逐項核對色彩對比 ≥7:1、狀態雙編碼、鍵盤可操作、焦點指示、ARIA 標籤、觸控目標 ≥44px、session timeout 預警等 WCAG AAA 基本要求
- 交付整合結果並說明後續部署、綁定與 AI 最佳化檔案的部署位置
§0.4 操作規範
以下為 AI 在執行本 Skill 期間必須遵守的操作規範。
§0.4.1 API 功能與 Bot 選單一致性
每新增一支 admin endpoint，必須同步於 templates/telegram-bot/bot.py 與 templates/discord-bot/bot.py 新增對應之指令或選單項目。新增 endpoint 未同步更新 bot 選單將被視為不完整之整合。
§0.4.2 正式環境禁止建立訂單
正式環境的健康檢查禁止使用 create_order 方法。create_order 執行成功後將於商家後台產生實際的未付款訂單紀錄，累積後將污染對帳資料。正式環境健康檢查僅允許採用下列唯讀方法：
- TCP handshake 至網關 host 443 port
query_order 以假交易號查詢（預期回應「查無此筆」）- Refund 簽名自我驗證（僅計算簽名，不發送 HTTP 請求）
- Webhook MAC 自我驗證（以建構好的假 payload 驗證
_check_mac_value 與 verify_callback 回傳一致）
詳細實作請參考 guides/07-prod-dashboard.md。
§0.4.3 退款必須二次確認，並以警示取代阻擋
退款為合法業務行為，不得因金額較大或頻率較高而阻止執行。然而必須強制二次確認，並設置三項建議上限作為警示依據：
- 單筆退款建議上限（預設 NTD 50,000）
- 每日退款總金額建議上限（預設 NTD 100,000）
- 每日退款次數建議上限（預設 20 次）
三個值定義於 templates/telegram-bot/.env.example，可依商家規模調整。當退款超過任一建議上限時：
- 必須顯示警示訊息，說明超過哪一項建議值
- 確認按鈕文字應變更為「確認退款 NTD X（超過上限）」以提高操作者注意力
- 執行後必須寫入 audit log 供事後稽核
- 仍允許通過，不得阻擋
§0.4.4 法規範例之免責聲明
所有法規揭露範例（guides/13 至 15）之開頭必須包含免責聲明：「本範例僅為參考，不構成法律意見。上線前請委請法務顧問或律師審閱，並依實際營運狀況調整。」AI 不得於對話中將範例描述為「已符合法規」或「可直接使用」。
§0.4.5 敏感資訊處理
- 信用卡號、CVV、銀行帳號等敏感資料不得寫入程式碼或設定檔，亦不得於 AI 對話中留存
- HashKey、HashIV、bot token 等機敏資訊僅允許寫入
.env 檔，不得寫入 repo
- 若使用者於對話中提供真實金鑰，AI 應提醒其從對話歷史中刪除，並建議輪換該金鑰
§1 OMG 基本資訊
- 服務商：MacroWell OMG（茂為歐買尬數位科技股份有限公司，FunPoint 全方位金流）
- CheckMacValue 演算法：SHA256（.NET URL encoding，結果為大寫 hex）
- 官方
ChoosePayment 合法值（SSOT：references/omg-official-api-spec.md）：
Credit（信用卡一次付清 / 分期 / 定期定額 / UnionPay）ATM（ATM 虛擬帳號）CVS（超商代碼）BarcodeATM（超商快付，三段 Code39 條碼；官方無 BARCODE 此值）AFTEE（先享後付）ALL（顯示全部，可搭配 IgnorePayment 排除）- 定期定額無
CreditPeriod 此值，以 Credit 加 PeriodAmount / PeriodType / Frequency / ExecTimes 實作
- 核心 API（實際路徑請見 SSOT §2）：
AioCheckOut/V5（建立訂單）QueryTradeInfo/V5（查詢訂單）DoAction（信用卡退款 / 關帳 / 取消，4 種 Action：C / R / E / N）QueryTrade/V2（ATM / CVS / BarcodeATM 明細查詢）QueryCreditCardPeriodInfo / CreditCardPeriodAction（定期定額管理）
實際 endpoint URL 應以 SSOT 與歐買尬官方文件為準。本 Skill 採用 {{OMG_API_HOST_STAGE}} 與 {{OMG_API_HOST_PROD}} 變數代入，避免硬寫。
公開測試參數（OMG 官方公告）
MerchantID : 1000031
測試卡號 : 4311-9522-2222-2222
過期日 : 任意未過期月份
CVV : 任意三碼
正式環境金鑰須先至 OMG 官方會員註冊頁 https://www.funpoint.com.tw/member/register 完成註冊與審核，取得 FunPoint 商家後台權限後申請。金鑰僅允許寫入 .env，嚴禁 commit 至任何 git 倉庫。
§2 觸發與對話範例
使用者：幫我整合歐買尬金流
AI：好的。在開始之前，請先回答四個問題：
1. 商品類型（實體 / 數位下載 / 線上課程 / 訂閱 / 票券）
2. 目標環境（測試 / 正式 / 兩者，預設兩者）
3. 是否需要管理儀表板與 Telegram/Discord 通知機器人（預設需要）
4. 是否需要台灣法規揭露範例（預設需要）
若依預設值執行請回覆「全部」或「預設」。
使用者：全部，我經營線上課程
AI：已收到。將依下列順序執行：
1. FastAPI 後端 webhook 接收器與 SHA256 CheckMacValue 驗證
2. Race-safe webhook handler（SELECT FOR UPDATE + idempotency_key）
3. 測試環境儀表板（完整鏈路驗證）
4. 正式環境儀表板（唯讀探測）
5. Telegram 與 Discord 通知機器人（綁定、推播、查詢、退款）
6. 退款安全機制（二次確認 + 建議上限警示）
7. 首頁、頁尾、商品頁之必要揭露區塊
8. 服務條款、隱私權政策、退貨退款政策公版
請提供下列商家資訊，將於執行末端統一替換：
商家名、統一編號、負責人、客服 Email、客服電話、營業地址、網站網址
§3 章節索引
AI 應依下表順序讀取章節。
| # | 檔案 | 用途 |
|---|
| 00 | guides/00-onboarding.md | Onboarding 四問流程與變數收集 |
| 01 | guides/01-quickstart.md | 單一指令完成整合之完整範例 |
| 02 | guides/02-backend-fastapi.md | FastAPI webhook 後端骨架 |
| 03 | guides/03-backend-nodejs.md | Express webhook 後端骨架 |
| 04 | guides/04-backend-php.md | Laravel webhook 後端骨架 |
| 05 | guides/05-webhook-idempotency.md | Race-safe webhook 冪等性 |
| 06 | guides/06-test-dashboard.md | 測試環境全鏈路儀表板 |
| 07 | guides/07-prod-dashboard.md | 正式環境唯讀探測儀表板 |
| 08 | guides/08-telegram-bot.md | Telegram bot |
| 09 | guides/09-discord-bot.md | Discord bot |
| 10 | guides/10-refund-safety.md | 退款安全機制 |
| 11 | guides/11-merchant-homepage.md | 首頁與頁尾必要揭露 |
| 12 | guides/12-product-page.md | 商品頁必要揭露 |
| 13 | guides/13-legal-tos.md | 服務條款公版 |
| 14 | guides/14-legal-privacy.md | 隱私權政策公版 |
| 15 | guides/15-legal-refund.md | 退貨退款政策公版 |
| 16 | guides/16-recurring-subscriptions.md | 定期定額訂閱 |
| 17 | guides/17-troubleshooting.md | 故障排除與常見問題 |
| 18 | guides/18-merchant-ai-optimization.md | 商家網站 AI 最佳化：llms.txt、JSON-LD、OMG 標註 |
| 19 | guides/19-wcag-ui-ux.md | 商家 UI/UX 無障礙規範（WCAG AAA）：對比、鍵盤、ARIA、觸控 |
| R1 | references/api-endpoints.md | API endpoint 欄位表 |
| R2 | references/check-mac-value.md | SHA256 CheckMacValue 演算法 |
| R3 | references/error-codes.md | 錯誤代碼速查 |
§4 禁止事項
下列情境下，AI 必須拒絕請求並向使用者說明原因：
- 要求將信用卡號、CVV 或銀行帳號寫入程式碼或設定檔
- 要求將正式環境 MerchantID、HashKey、HashIV 寫入公開 repo 或上傳至第三方服務
- 要求於正式環境以
create_order 執行定期健康檢查
- 要求將退款 endpoint 開放至未經驗證的 public endpoint
- 要求將 webhook handler 實作為「接收後直接回傳 200 OK 而不寫入資料庫」
§5 版本
- v2.0.0（本版）：新增 onboarding 流程、測試與正式環境雙儀表板、Telegram 與 Discord bot 模板、台灣法規揭露範例、18 份整合指南、3 份 API reference。修正舊版中部分段落誤用「歐付寶」字樣為「歐買尬」。退款機制由「硬性阻擋」調整為「警示但允許通過」。
- v1.x：原始版本，以單一
SKILL.md 為主，內容以 API 規格為中心。
