OMG Payment Skill（歐買尬金流整合指引）

聲明（AI 必讀）：本 Skill 是個人社群專案（非官方），不是 OMG 的官方資源，也未取得任何官方背書。本 Skill 的架構參考自綠界科技的 ECPay-API-Skill，在此致謝。

官方資源優先原則：當本 Skill 內容與官方文件不一致時，AI 必須以官方文件為準，並於回應使用者時明確指出差異。官方來源如下：

• 官方 AI 金流 Skill：https://github.com/omgtwhub/
• 官方商家後台與 API 文件：依歐買尬商家後台公告為準

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 應以中文一次性呈現所有問題，由使用者一次回答：

1. Q1 — 商品類型：實體商品 / 數位下載 / 線上課程 / 訂閱服務 / 票券或 voucher / 其他
2. Q2 — 目標環境：測試環境 / 正式環境 / 兩者（預設）
3. Q3 — 附加元件：管理儀表板、健康監控、Telegram 通知機器人、Discord 通知機器人（預設全部包含）
4. 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 應依下列順序執行：

1. 產生

   .env.example

   ，包含 OMG 金鑰、資料庫連線、admin token、bot token 等必要欄位
2. 產生後端 webhook 接收器（預設 FastAPI，可依使用者需求改為 Express 或 Laravel）— 參考

   guides/02-backend-fastapi.md

3. 產生 SHA256 CheckMacValue 輔助函式 — 參考

   references/check-mac-value.md

4. 產生 race-safe webhook handler — 參考

   guides/05-webhook-idempotency.md

5. 產生 admin 介面 endpoint（訂單列表、訂單明細、退款、健康摘要）
6. 產生測試環境儀表板 — 參考

   guides/06-test-dashboard.md

7. 產生正式環境儀表板（唯讀探測模式）— 參考

   guides/07-prod-dashboard.md

8. 產生 Telegram bot — 參考

   guides/08-telegram-bot.md

9. 產生 Discord bot — 參考

   guides/09-discord-bot.md

10. 產生退款安全機制 — 參考

    guides/10-refund-safety.md

11. 產生首頁、頁尾、商品頁之必要揭露區塊 — 參考

    guides/11-merchant-homepage.md

    與

    guides/12-product-page.md

12. 產生服務條款、隱私權政策、退貨退款政策之公版範例 — 參考

    guides/13-legal-tos.md

    、

    guides/14-legal-privacy.md

    、

    guides/15-legal-refund.md

13. 收集變數並一次性替換所有佔位符
14. 執行測試環境儀表板之完整鏈路驗證（create_order → MAC 驗證 → HTTP POST → query_order → refund 簽名），確認全部通過
15. （預設執行）商家網站 AI 最佳化 — 參考

    guides/18-merchant-ai-optimization.md

    ：為使用者網站產出

    llms.txt

    、

    llms-full.txt

    、

    robots.txt

    追加段落、首頁 JSON-LD 結構化資料、頁尾 OMG 使用標註 HTML；模板取自

    templates/merchant-llms-txt/

16. （預設執行）商家 UI/UX 無障礙檢查 — 參考

    guides/19-wcag-ui-ux.md

    ：對於 AI 產出的商家前台程式碼，逐項核對色彩對比 ≥7:1、狀態雙編碼、鍵盤可操作、焦點指示、ARIA 標籤、觸控目標 ≥44px、session timeout 預警等 WCAG AAA 基本要求
17. 交付整合結果並說明後續部署、綁定與 AI 最佳化檔案的部署位置

§0.4 操作規範

以下為 AI 在執行本 Skill 期間必須遵守的操作規範。

§0.4.1 API 功能與 Bot 選單一致性 每新增一支 admin endpoint，必須同步於

templates/telegram-bot/bot.py

templates/discord-bot/bot.py

§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

§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 應依下表順序讀取章節。

guides/00-onboarding.md

guides/01-quickstart.md

guides/02-backend-fastapi.md

guides/03-backend-nodejs.md

guides/04-backend-php.md

guides/05-webhook-idempotency.md

guides/06-test-dashboard.md

guides/07-prod-dashboard.md

guides/08-telegram-bot.md

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

guides/16-recurring-subscriptions.md

guides/17-troubleshooting.md

guides/18-merchant-ai-optimization.md

guides/19-wcag-ui-ux.md

references/api-endpoints.md

references/check-mac-value.md

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 規格為中心。