綠界科技官方出品 — 由 ECPay 團隊開發與維護，內容與 API 同步更新。

當前版本：V1.5.4

• 前置需求
• 這是什麼？
• 快速開始
• 使用範例
• 涵蓋服務
• 特色
• 指南索引
• 目錄結構
• AI 查詢處理流程
• 測試環境快速參考
• 常見問題
• 安全政策
• API 規格索引（references/）
• 授權

使用本 Skill 需要以下任一 AI 程式開發助手：

ECPay Skill 是一個 AI 知識套件——安裝到 AI 程式開發助手（Claude Code、VS Code Copilot Chat、GitHub Copilot CLI、Cursor、Windsurf 等），或透過 ChatGPT GPT Builder、Google AI Studio 等平台上傳後，AI 就能根據你的需求，直接生成綠界 API 串接程式碼、診斷錯誤、引導完整串接流程。

不需要自己翻文件，用自然語言描述需求即可。

AI 程式開發助手是安裝在開發者電腦上（終端機或程式碼編輯器內）的 AI 工具，能讀取專案程式碼、用自然語言對話、直接生成或修改程式碼。它不是瀏覽器裡的 ChatGPT——而是嵌入開發工作流程的專業工具。上方「前置需求」表格列出的 Claude Code、VS Code Copilot Chat、GitHub Copilot CLI、Cursor、Windsurf 等都屬於這類工具。

打個比方：AI 程式開發助手就像一個聰明但對你的業務一無所知的新進工程師。AI Skill 就是交給他的「工作手冊」——安裝 ECPay Skill 後，這個 AI 就變成了熟悉綠界全系列 API 的串接專家。

技術上，AI Skill 是一組 Markdown 文件（入口為 SKILL.md），包含決策樹、整合指南、加密範例和官方 API 索引。AI 偵測到 ECPay 相關關鍵字時會自動啟動，依據這些知識回答問題。

第一次接觸 ECPay？先看這 5 個核心概念（完整術語表見 guides/00）：

flowchart LR
    A["📦 1. 安裝<br/>git clone 到 skill 目錄"] --> B["💬 2. 提問<br/>用自然語言描述需求"] --> C["✅ 3. 完成！<br/>AI 產出可用程式碼<br/>+ 串接指引"]

三步驟（純文字版）：① git clone 安裝 Skill → ② 用自然語言描述需求（例：「我要信用卡收款」）→ ③ AI 直接產出可用程式碼 + 串接指引

💡 給非技術人員：安裝後你不需要懂程式。只要用中文告訴 AI「我要信用卡收款」，它就會產出完整的程式碼和步驟說明，交給工程師即可。

安裝路徑快速對照（詳細說明見下方各平台段落）：

平台	安裝指令	驗證方式
Google AI Studio（非技術人員推薦）	上傳檔案 + 貼 System Instructions，見 SETUP.md	問「測試 MerchantID？」→ 3002607
VS Code Copilot Chat（非技術人員也適用）	下載 ZIP → 用 VS Code 開啟資料夾 → 自動載入，見 vscode_copilot.md	同上
Visual Studio 2026（C#/.NET 推薦）	Clone 至專案 + 建立 .github/copilot-instructions.md，見 visual_studio_2026.md	同上
Claude Code	git clone ...ECPay-API-Skill.git ~/.claude/skills/ecpay	同上
GitHub Copilot CLI	Clone 後將 .github/copilot-instructions.md 內容貼至目標專案	同上
Cursor	Clone 至專案 + 建立 AGENTS.md 引用	同上
Windsurf	git clone ...ECPay-API-Skill.git .windsurf/skills/ecpay	同上
OpenClaw	git clone ...ECPay-API-Skill.git ~/.openclaw/skills/ecpay	同上
ChatGPT GPTs	上傳 SKILL_OPENAI.md 至 GPT Builder Knowledge	同上
OpenAI Codex CLI	讀取 AGENTS.md，見 SETUP.md	同上
Google Gemini CLI	讀取 GEMINI.md，見 SETUP.md	同上

Claude Code

# 個人全域安裝（推薦，所有專案共享）
git clone https://github.com/ECPay/ECPay-API-Skill.git ~/.claude/skills/ecpay

# 或專案層級安裝（僅當前專案）
git clone https://github.com/ECPay/ECPay-API-Skill.git .claude/skills/ecpay

驗證：開啟 Claude Code，輸入 /ecpay 或問「What skills are available?」，確認 ECPay Skill 出現在清單中。

VS Code Copilot Chat（非技術人員也適用，圖形介面操作）

💡 最簡單的安裝方式：下載 ZIP → 解壓縮 → 用 VS Code 開啟資料夾 → 自動載入，不需要終端機操作。 完整圖文步驟見 vscode_copilot.md。

Visual Studio 2026（C# / .NET 開發者推薦，支援 Agent Mode）

💡 Visual Studio 2026 (v18.0+) 和 2022 (v17.14+) 內建 GitHub Copilot，支援 Custom Instructions、Agent Mode、Prompt Files。GitHub Copilot Free 方案即可使用。 完整安裝與使用步驟見 visual_studio_2026.md。

# Clone 至專案目錄
git clone https://github.com/ECPay/ECPay-API-Skill.git .ecpay-skill

# 建立 Custom Instructions（將 ECPay Skill 知識載入 Copilot）
# 見 visual_studio_2026.md 中的 copilot-instructions.md 範本

安裝後，在 Copilot Chat 中詢問「綠界 AIO 金流的測試 MerchantID 是多少？」，若回應為 3002607 表示 Skill 已載入。

GitHub Copilot CLI（終端機工具，適合工程師）

💡 自動載入：本 repo 的 .github/copilot-instructions.md 會被 GitHub Copilot CLI 在此 repo 中工作時自動讀取——若你已 clone 本 repo 並在其中開發，Copilot 無需任何額外設定即可感知 ECPay Skill 知識。

若要在其他專案中使用 ECPay Skill，需手動將 ECPay Skill 的指令內容引入你的目標專案：

# 方式一：Clone 本 repo，再將 .github/copilot-instructions.md 的內容複製到
# 你的目標專案根目錄的 .github/copilot-instructions.md 中（手動貼上，非自動 include）
git clone https://github.com/ECPay/ECPay-API-Skill.git /path/to/ecpay-skill

# 方式二：Clone 到目標專案的子目錄，再手動將 .github/copilot-instructions.md 的
# 完整內容貼至目標專案的 .github/copilot-instructions.md 末尾
git clone https://github.com/ECPay/ECPay-API-Skill.git .github/skills/ecpay

⚠️ GitHub Copilot CLI 只讀取專案根目錄的 .github/copilot-instructions.md，不會自動讀取子目錄的 instructions 檔案。因此，clone 到 .github/skills/ecpay/ 後，需在目標專案的根目錄 .github/copilot-instructions.md 中明確引用，Copilot 才能載入 ECPay Skill 知識。

Cursor

Cursor 使用 .cursor/rules/ 目錄載入規則，並支援 AGENTS.md 自動偵測。

# 方式一（推薦）：Clone 至專案目錄，Cursor 可透過 AGENTS.md 自動偵測
git clone https://github.com/ECPay/ECPay-API-Skill.git .ecpay-skill

Clone 後，在專案根目錄建立或編輯 AGENTS.md，加入以下內容：

## ECPay Skill
讀取 `.ecpay-skill/SKILL.md` 作為 ECPay 整合知識庫入口。
完整指南位於 `.ecpay-skill/guides/`（28 份），即時 API 規格索引位於 `.ecpay-skill/references/`。

安裝後，在 Cursor 中詢問「綠界 AIO 金流的測試 MerchantID 是多少？」，若回應為 3002607 表示 Skill 已載入。

Windsurf

# 專案層級（提交至 repo，團隊共用）
git clone https://github.com/ECPay/ECPay-API-Skill.git .windsurf/skills/ecpay

# 或個人全域安裝（所有專案共享，注意：Windsurf 全域路徑為 ~/.codeium/windsurf/skills/）
git clone https://github.com/ECPay/ECPay-API-Skill.git ~/.codeium/windsurf/skills/ecpay

安裝後，在 Windsurf 中詢問「綠界 AIO 金流的測試 MerchantID 是多少？」，若回應為 3002607 表示 Skill 已載入。

OpenClaw

# 安裝至個人共用 skills（所有 agent 共享，推薦）
git clone https://github.com/ECPay/ECPay-API-Skill.git ~/.openclaw/skills/ecpay

# 或 workspace 層級（僅當前專案）
git clone https://github.com/ECPay/ECPay-API-Skill.git skills/ecpay

詳細步驟（含設定驗證）見 SETUP.md §OpenClaw。

ChatGPT GPTs（custom GPT）

1. 開啟 GPT Builder，建立新的 GPT
2. 在 Configure → Knowledge，上傳 SKILL_OPENAI.md（檔案超過 8,000 字元，無法貼入 Instructions）
3. 同樣在 Knowledge，上傳 guides/、references/ 等關鍵檔案（最多 20 個）
4. 詳細步驟（含建議上傳的檔案清單）見 SETUP.md §ChatGPT

其他框架：將此資料夾放入框架的 skill 目錄。

生產環境建議固定到特定版本以避免非預期的破壞性變更：

git clone https://github.com/ECPay/ECPay-API-Skill.git ~/.claude/skills/ecpay
cd ~/.claude/skills/ecpay
git checkout v1.0   # 固定至 v1.0

# 之後如需升級
git fetch --tags && git checkout v1.5

查看所有可用版本：git tag -l。開發環境使用 git pull 取得最新版即可。

安裝完成後，在 AI 助手中輸入以下測試問題，確認 Skill 正確載入：

「綠界 AIO 金流的測試 MerchantID 是多少？」

若 AI 回應為「3002607」，表示 Skill 運作正常。若 AI 回答不確定或僅給出通用建議，請檢查安裝路徑是否正確。

安裝後，在 AI 助手中直接用自然語言提問。提到 ECPay 相關關鍵字時 Skill 會自動啟動：

ecpay, 綠界, 信用卡串接, 超商取貨, 電子發票, CheckMacValue, 站內付, 金流串接, 物流串接, 定期定額, 綁卡, 退款, 折讓...

Claude Code 快速指令（選用）：將 commands/ 內的 .md 檔複製到專案 .claude/commands/，即可使用以下 6 個快速指令：

💡 提問技巧：提問時請明確說明要串接的服務名稱（例：AIO 全方位金流、站內付 2.0、電子發票 B2C、國內超商物流），AI 才能精準選用對應規格。若同時安裝多個支付服務的 Skill（如 TapPay、LinePay 等），請加上「ECPay」或「綠界」確認 Skill 來源。

💬 「幫我用 Go 寫一個完整的 ECPay AIO 信用卡一次付清串接」

💬 「我想用綠界 AIO 提供 ATM 虛擬帳號付款，Python Flask」

💬 「用 TypeScript 串接綠界 AIO 超商代碼繳費」

💬 「我的 SaaS 要用 ECPay AIO 做定期定額訂閱扣款，Java Spring Boot」

💬 「綠界 AIO 信用卡分期付款怎麼串？C# ASP.NET」

💬 「想在我的網站加上 ECPay BNPL 先買後付，Ruby on Rails」

💬 「我要用 Node.js 串接綠界站內付 2.0 信用卡付款（React 前後端分離架構）」

💬 「ECPay 站內付綁卡快速付款怎麼做？Vue + Express」

💬 「我的 iOS App 要用 ECPay 站內付 2.0 串接信用卡付款（使用 App SDK 方案）」

💬 「後台自動扣款不需消費者操作，要用 ECPay 幕後授權 API 還是站內付 2.0 綁卡代扣？Kotlin」

💬 「怎麼用 Python 查詢綠界 AIO 訂單狀態？」

💬 「客戶要求退款，ECPay AIO 信用卡如何發起退款？Node.js（請區分當日取消與事後請退）」

💬 「用 Python 串接綠界 B2C 電子發票開立」

💬 「我們公司對公司交易，要用 ECPay 開 B2B 電子發票，Java」

💬 「綠界發票折讓怎麼做？消費者部分退貨需要開折讓」

💬 「我要用 C# 串接 ECPay 超商取貨付款（7-11 / 全家）」

💬 「用 Go 串接綠界宅配物流，需要列印託運單」

💬 「ECPay 跨境物流怎麼串？要寄到香港和馬來西亞」

💬 「我們要用綠界做演唱會電子票券，Rust」

💬 「我需要用綠界做完整電商：收款後自動開發票再出貨，Python Django」

💬 「ECPay AIO 的 CheckMacValue 驗證一直失敗，錯誤碼 10400002」

💬 「綠界 AES 解密回來是亂碼，站內付 2.0 回呼解不開」

💬 「ECPay AIO 的 ReturnURL Callback 一直收不到，伺服器 IP 已開放了」

💬 「綠界站內付 2.0 的 CreatePayment API 一直 404，GetToken 成功但建立交易失敗」

💬 「綠界測試環境都通了，要怎麼安全切換到正式環境？」

💬 「門市要用 ECPay POS 刷卡機，怎麼串接？」

💬 「直播賣東西想用綠界收款網址讓觀眾直接付款」

💬 「Apple Pay 可以用 ECPay 收嗎？Swift iOS App」

信用卡一次付清、信用卡分期、信用卡定期定額、ATM 虛擬帳號、超商代碼、超商條碼、WebATM、TWQR、BNPL 先買後付、微信支付、Apple Pay、銀聯

• 134 個經官方驗證的 PHP 範例（可翻譯為 12 種主流語言或其他語言）
• 28 份深度整合指南（從入門到上線，含 3 個站內付子指南）
• 12 種語言的加密函式實作（Python、Node.js、TypeScript、Java、C#、Go、C、C++、Rust、Swift、Kotlin、Ruby）
• 19 份官方 API 技術文件索引 + 1 份索引說明（共計 431 個 URL，可即時查閱原始文件）
• 決策樹自動推薦最適方案
• 跨服務整合場景（收款 + 發票 + 出貨）
• 內建除錯指南和上線檢查清單
• 即時規格更新——AI 在產生程式碼前會透過 references/ 即時讀取 developers.ecpay.com.tw 最新 API 規格，不依賴過期的靜態文件
• 21 個跨語言加密測試向量（CheckMacValue × 8、AES × 9、URL Encode × 4），CI 自動驗證（validate.yml）
• 6 個 Claude Code 快速指令（/ecpay-pay、/ecpay-invoice、/ecpay-debug 等）

• scripts/validate-ai-index.sh：驗證 guides/13、14、24 中的 AI Section Index 行號是否準確（確認行號指向的行為 # 開頭的標題）。維護者更新這些 guide 的章節結構後建議執行此指令碼確認行號索引無誤。
• scripts/validate-version-sync.sh：驗證 9 個平台入口文件（SKILL.md 為版本來源，另外 8 個被驗證）的版本號是否一致。版本號異動後執行：

  bash scripts/validate-version-sync.sh

• scripts/validate-agents-parity.sh：驗證 AGENTS.md（Codex CLI 入口）與 GEMINI.md（Gemini CLI 入口）的決策樹、關鍵規則、測試帳號三大區段是否一致。修改任一文件後執行：

  bash scripts/validate-agents-parity.sh

• test-vectors/verify.py：一次驗證所有 21 個加密測試向量（CheckMacValue / AES / URL Encode）。CI（validate.yml）自動執行；本機執行需先安裝依賴後執行：

  pip install pycryptodome
  python test-vectors/verify.py

• scripts/SDK_PHP/：官方 ECPay PHP SDK（唯讀參考）。當前版本：1.3.2506240（2025-06-24）。若 SDK 有新版請比對 scripts/SDK_PHP/CHANGELOG.md 後更新，不要直接修改 SDK 內容。

本 repo 有兩個 GitHub Actions workflow 守護知識庫完整性，無需人工介入：

觸發：PR 送出 或 push 到 main，且修改了 guides/、SKILL.md 等核心文件時自動執行。

依序執行四道檢查，任一失敗 → PR 無法合併：

觸發：每週一 UTC 02:00 自動排程，另外修改 references/ 時或手動觸發也會執行。

以 8 執行緒並行 curl 檢查 references/ 目錄下全部 431 個 developers.ecpay.com.tw URL：

URL 問題修復後，workflow 再次通過時會自動關閉對應 Issue。

💡 若需立即檢查 URL 可達性，可至 GitHub Actions 頁籤 → Validate Reference URLs → Run workflow 手動觸發。

ECPay API 使用不同的認證和請求格式，本 Skill 完整涵蓋：

注意：直播收款的 API 請求使用 AES-JSON（無 CMV）；其 ReturnURL callback 驗證需使用 ECTicket 式 CheckMacValue（公式同電子票證），詳見 guides/17 §直播收款。

生成非 PHP 程式碼時，AI 同時載入目標語言的規範檔。涵蓋命名慣例、型別定義、錯誤處理、HTTP 設定、Callback Handler 模板、URL Encode 注意事項。

ecpay-skill/
├── SKILL.md                    # AI 進入點（Claude Code / Cursor / Windsurf / OpenClaw）：決策樹 + 導航
├── SKILL_OPENAI.md             # ChatGPT GPTs（custom GPT）Instructions 設定檔
├── AGENTS.md                   # OpenAI Codex CLI AI 進入點
├── GEMINI.md                   # Google Gemini CLI AI 進入點
├── SETUP.md                    # 統一安裝指南（Codex CLI / Gemini CLI / OpenClaw / ChatGPT GPTs）
├── README.md                   # 本文件
├── CONTRIBUTING.md             # 貢獻指南
├── SECURITY.md                 # 安全政策（漏洞通報、憑證安全須知）
├── LICENSE                     # All Rights Reserved
├── .github/                    # GitHub 社群模板（Issue/PR 模板、CI workflow）
│   └── copilot-instructions.md # VS Code Copilot Chat / GitHub Copilot CLI AI 自動載入入口（在此 repo 工作時自動生效）
├── test-vectors/               # 跨語言加密驗證用測試向量（CMV + AES + URL Encode，共 21 個）
│   └── verify.py               # 一鍵驗證所有向量（pip install pycryptodome 後執行）
├── commands/                   # Claude Code 快速指令（6 個 /ecpay-* 指令）
├── guides/                     # 28 份深度整合指南（ChatGPT GPTs 依 SETUP.md §ChatGPT 選擇上傳子集）
│   └── lang-standards/         # 12 語言程式規範（Python/Node.js/TS/Go/Java/C#/Kotlin/Ruby/Rust/Swift/C/C++）
├── references/                 # 官方 API 文件 URL 索引（19 個檔案，431 個 URL）— AI 即時讀取入口
│   ├── Payment/   (8 個)
│   ├── Invoice/   (4 個)
│   ├── Logistics/ (3 個)
│   ├── Ecticket/  (3 個)
│   └── Cart/      (1 個)
└── scripts/
    ├── validate-ai-index.sh    # AI Section Index 行號驗證指令碼
    └── SDK_PHP/                # 官方 PHP SDK + 134 個範例
        └── example/
            ├── Payment/Aio/        (20 個)
            ├── Payment/Ecpg/       (24 個)
            ├── Invoice/B2C/        (19 個)
            ├── Invoice/B2B/        (23 個)
            ├── Logistics/Domestic/ (24 個)
            ├── Logistics/AllInOne/ (16 個)
            └── Logistics/CrossBorder/ (8 個)

AI 助手在回答開發者問題時，依循以下順序參照知識庫：

開發者提問 → SKILL.md 決策樹分析需求
  ├── 判斷服務類型（金流 / 物流 / 發票 / 票證）
  ├── 判斷協議模式（CMV-SHA256 / AES-JSON / AES-JSON+CMV / CMV-MD5）
  └── 路由到對應的 guide + reference

guides/XX-*.md  →  了解「怎麼做」
  ├── 整合流程與架構邏輯
  ├── 程式碼範例與常見陷阱
  └── 參數表（標記為 SNAPSHOT，僅供理解用）

references/*/  →  取得「最新規格」
  ├── 讀取 reference 檔案 → 找到對應 URL
  ├── 使用平台工具存取 developers.ecpay.com.tw
  └── 取得最新端點、參數定義、回應格式

1. SKILL.md 決策樹  ──→  判斷需求，路由到對應 guide
2. guides/XX         ──→  讀取整合流程、架構邏輯、注意事項
3. scripts/SDK_PHP/  ──→  讀取官方 PHP 範例作為翻譯基礎（需要產生程式碼時）
4. references/       ──→  ⭐ 即時存取最新 API 規格（產生程式碼前必做）
5. guides/13 或 14   ──→  加密實作參考（CheckMacValue 或 AES）
6. test-vectors/     ──→  提供測試向量供驗證

核心原則：guides/ 告訴 AI「怎麼串接」，references/ 告訴 AI「串接什麼」。 產生 API 呼叫程式碼前，必須透過 references/ 取得最新規格，不可僅依賴 guides/ 中的 SNAPSHOT 參數表。

不同 AI 平台各自讀取對應的入口檔案，理解這個對應關係有助於正確設定和排查問題：

ChatGPT GPTs 注意：無法直接讀取 references/ 中的 URL，改用 Web Search 搜尋官方文件。 若 Web Search 無法取得結果，以 guides/ SNAPSHOT 為備援並標示「此為 SNAPSHOT，可能非最新版本」。

無需申請，使用以下共用測試帳號即可立即開始開發：

💡 快速測試提示：建立訂單時設定 SimulatePaid=1，無需真實信用卡即可模擬付款成功。 ⚠️ 注意：金流、物流、發票使用不同 HashKey / HashIV，切勿混用。

測試信用卡：4311-9522-2222-2222，CVV：任意 3 位，有效期：任意未來日期，3DS：1234。

完整帳號（含離線發票、電子票證平台商等）見 guides/00-getting-started.md §測試帳號。

Q：不用 PHP 可以嗎？ A：可以。本 Skill 支援 12 種語言的加密函式實作，並提供 HTTP 協議參考（guides/20）讓其他語言也能從零實作。PHP 範例作為翻譯基底，AI 會自動轉換為你的目標語言。

Q：AIO 和站內付 2.0 怎麼選？ A：AIO 會跳轉到綠界付款頁，整合最簡單；站內付 2.0 讓消費者在你的網站內完成付款，適合前後端分離架構（React/Vue/Angular）。詳見 guides/01 和 guides/02。

Q：Callback（付款通知）收不到怎麼辦？ A：參考 guides/15 §2 排查流程 + guides/22 各服務 Callback 格式彙總。常見原因：URL 不可達、未回應 1|OK、防火牆擋 ECPay IP。

Q：怎麼從測試環境切換到正式環境？ A：參考 guides/16 上線檢查清單，逐項替換 MerchantID、HashKey/HashIV、API domain。

Q：AI 生成的程式碼可以直接使用嗎？ A：AI 基於 134 個官方驗證的 PHP 範例和 12 語言加密實作生成程式碼，品質高但仍建議人工驗證。特別是金額、加密邏輯、Callback 處理等關鍵路徑應搭配測試環境驗證。

Q：API 規格更新時，AI 會讀到最新的嗎？ A：會。references/ 目錄存放 431 個指向 developers.ecpay.com.tw 的 URL 索引（不是靜態副本），AI 會即時讀取最新官方規格。ChatGPT GPTs 因平台限制改以 Web Search 替代。

• 綠界科技官網
• 開發者文件
• PHP SDK GitHub

本 Skill 基於綠界科技官方 API 技術文件及官方 PHP SDK 開發。如需驗證內容準確性：

1. API 規格：比對 developers.ecpay.com.tw 官方文件
2. PHP SDK：比對 ECPay 官方 GitHub 的範例程式碼
3. 技術諮詢：聯繫綠界科技 系統分析部 sysanalydep.sa@ecpay.com.tw 確認

歡迎貢獻！詳見 CONTRIBUTING.md。

安全漏洞通報與憑證安全須知請見 SECURITY.md。

• 僅支援新台幣（TWD）
• references/ URL 索引需要網路連線才能即時讀取最新 API 規格
• ChatGPT GPTs 無法直接讀取 references/ 檔案（透過 Web Search 替代，可靠性略低於 web_fetch 直讀）
• AI 翻譯品質可能因模型與語言組合而異，生成的程式碼片段應經人工驗證

All Rights Reserved — 詳見 LICENSE

本著作之一切著作權及智慧財產權歸綠界科技股份有限公司所有。您可檢視、研讀及搭配 AI 編程助手參考使用，但不得重新散布、轉授權或建立衍生著作用於商業銷售。