ecpay-api-skill

ECPay API Skill — 綠界科技 AI API整合助手

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

當前版本:V3.4

目錄

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

前置需求

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

平台	需求	安裝指引
VS Code Copilot Chat	VS Code + GitHub Copilot 訂閱	vscode_copilot.md
Visual Studio 2026	Visual Studio 2026 (v18.0+) + GitHub Copilot	visual_studio_2026.md
Claude Code	Claude 訂閱或 Anthropic Console API 帳號	安裝文件
GitHub Copilot CLI	GitHub Copilot 訂閱	安裝文件
Cursor	Cursor 安裝完成	下載頁面
OpenAI Codex CLI	OpenAI 帳號；npm install -g @openai/codex	SETUP.md §CLI
Google Gemini CLI	Google 帳號；npm install -g @google/gemini-cli	SETUP.md §CLI

這是什麼？

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

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

AI 程式開發助手是什麼？

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

AI Skill 是什麼？

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

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

💼 給管理決策者

常見疑問	說明
為什麼不直接看官方文件？	傳統做法：工程師逐頁翻 API 文件 → 理解規格 → 寫程式 → 除錯來回。安裝本 Skill 後：用中文描述需求 → AI 直接產出可用程式碼 + 串接指引，大幅縮短串接週期
安全嗎？	本 Skill 以 Markdown 知識檔為核心，不收集任何資料、不連線至第三方伺服器。密鑰由開發者自行管理，從不寫入 Skill 檔案
程式碼品質有保障嗎？	所有範例基於綠界官方 PHP SDK（134 個驗證範例），API 規格透過 references/ 即時連結官網最新版本，不依賴過期文件
需要額外付費嗎？	本 Skill 免費提供參考使用（版權所有，詳見 LICENSE）

這個 Skill 能做什麼？

能力	說明
需求分析	根據你的場景（電商、訂閱、門市、直播等）推薦最適合的 ECPay 方案
程式碼生成	基於 134 個驗證過的 PHP 範例，翻譯為 12 種主流語言（或其他語言）
即時除錯	診斷 CheckMacValue 失敗、AES 解密錯誤、API 錯誤碼等串接問題
完整流程	引導收款 → 發票 → 出貨的端到端整合
上線檢查	逐項檢查安全性、正確性、合規性

快速開始

核心術語速查

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

術語	白話解釋
MerchantID	你的商店編號（由綠界發給你，金流 / 物流 / 發票各服務帳號不同）
HashKey / HashIV	兩把密鑰，加密用的，絕對不能外洩（像你家大門的鑰匙）
CheckMacValue	簽名驗證碼——你和綠界雙方各用密鑰算出簽名，對得上才代表資料沒被竄改
Callback（ReturnURL）	綠界付款完成後，從背景通知你的伺服器的機制（伺服器對伺服器，不是瀏覽器跳轉）
SimulatePaid	設為 1 就能模擬付款成功，測試時不用真刷卡
電子收據（V3.0+）	一般 / 公益 / 政治獻金三種非發票憑證。與電子發票共用 domain einvoice.ecpay.com.tw 但端點為 /Receipt/*，支援 AES-CBC 與 AES-GCM 雙加密模式（guides/25）

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

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

💡 安裝後用中文告訴 AI「我要信用卡收款」，它就會產出完整的程式碼和步驟說明。

1. 安裝

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

平台	安裝指令	驗證方式
VS Code Copilot Chat	下載 ZIP → 用 VS Code 開啟資料夾 → 自動載入，見 vscode_copilot.md	同上
Visual Studio 2026	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 引用	同上
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 API 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 API Skill 知識載入 Copilot）
# 見 visual_studio_2026.md 中的 copilot-instructions.md 範本

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

⚠️ 常見誤區：copilot-instructions.md 必須建立在你自己專案的根目錄 .github/ 下，不是 clone 下來的 .ecpay-skill/.github/copilot-instructions.md（後者是維護本 repo 用的開發指令，不含測試帳號）。GitHub Copilot 只會讀取「目前開啟的方案（solution）根目錄」那一份。若驗證時回 2000132 而非 3002607，即代表指令檔未被載入——完整排查見 visual_studio_2026.md §常見問題。

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

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

若要在其他專案中使用 ECPay API Skill，需手動將 ECPay API 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 API 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 API Skill
讀取 `.ecpay-skill/SKILL.md` 作為 ECPay 整合知識庫入口。
完整指南位於 `.ecpay-skill/guides/`（29 份），即時 API 規格索引位於 `.ecpay-skill/references/`。

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

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

版本固定（生產環境建議）

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

git clone https://github.com/ECPay/ECPay-API-Skill.git ~/.claude/skills/ecpay
cd ~/.claude/skills/ecpay

git tag -l               # 列出所有可用版本
git checkout <版本 tag>   # 固定至指定版本，例如 git checkout v3.3

# 升級：git fetch --tags 後再 checkout 新的 tag

💡 開發環境使用 git pull 取得最新版即可；生產環境建議固定 tag。

驗證安裝

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

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

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

2. 使用

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

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

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

指令	用途
/ecpay-pay	串接金流（AIO / 站內付 2.0 / 幕後授權）、查詢、退款、Callback
/ecpay-invoice	串接電子發票（B2C / B2B / 離線）
/ecpay-logistics	串接物流（國內 / 全方位 / 跨境）
/ecpay-ecticket	串接ECTicket（價金保管 / 純發行）
/ecpay-debug	除錯排查 + CheckMacValue/AES 加密驗證
/ecpay-go-live	上線前檢查清單

3. 使用範例

💡 以下範例可直接複製貼上給任何 AI 助手使用（含免費模型）。每個 Prompt 已包含完整的測試帳號、環境網址、加密規則與注意事項，無需額外補充即可產出可用程式碼。

完整 Prompt 範例集（40 個詳盡範例） → docs/prompt-examples.md

分類	範例數	涵蓋語言	連結
金流 — AIO 全方位金流	7	Go, Python, TypeScript, Java, C#, Ruby, Kotlin	信用卡、ATM、超商代碼、分期、定期定額、BNPL、TWQR
金流 — 站內付 2.0	4	Node.js+React, Vue+Express, Swift, Kotlin	前後端分離、綁卡快速付、iOS/Android App
金流 — 幕後授權 / 查詢 / 退款	4	Python, Node.js, Go	幕後取號、訂單查詢、退款、定期定額管理
電子發票	4	Python, Java, C#, Rust	B2C 開立、B2B 開立、折讓、作廢+查詢
電子收據（V3.0+）	4	Python, TypeScript, Go, C#	一般收據、公益捐贈、政治獻金（AES-GCM）、查詢+修改+作廢+通知
物流	4	C#, Go, TypeScript, PHP	超商取貨付款、宅配+列印、跨境物流、狀態查詢
ECTicket	2	Rust, C++	票券發行、核銷+退票
跨服務整合	2	Python Django, Node.js	收款+發票+出貨、訂閱制+自動開發票
除錯與排查	5	通用	CheckMacValue 失敗、AES 解密亂碼、404 錯誤、Callback 收不到、驗證重試
上線與環境切換	1	通用	測試→正式完整檢查清單
特殊場景	3	Node.js, Ruby, Swift	POS 刷卡機、直播收款、Apple Pay

涵蓋服務

服務	內容	對應指南
金流	AIO 全方位金流（All-In-One）、ECPG 線上金流（站內付 2.0、綁定信用卡代扣、幕後授權、幕後取號）	guides/01-03
物流	國內物流（超商取貨 + 宅配）、全方位物流、跨境物流	guides/06-08
電子發票	B2C（企業對消費者）、B2B（企業對企業，交換 + 存證模式）、離線	guides/04-05, 18
電子收據（V3.0+ 新增）	一般收據、公益捐贈、政治獻金；支援 AES-CBC 與 AES-GCM 雙加密模式（首個啟用 GCM 的 ECPay 服務）	guides/25
ECTicket	價金保管（使用後核銷 / 分期核銷）、純發行	guides/09
購物車	WooCommerce、OpenCart、Magento、Shopify	guides/10
POS 刷卡機 + 直播收款	實體門市刷卡機串接 / 直播電商收款網址	guides/17

支援的付款方式

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

特色

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

維護工具

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

  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：一次驗證所有 25 個加密測試向量（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 內容。

CI 自動驗證

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

validate.yml（程式碼品質門禁）

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

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

步驟	指令碼	檢查內容
1	validate-ai-index.sh	guides/13、14、23 的 AI Section Index 行號是否仍指向正確的 # 標題行（行號錯誤會讓 AI 查到錯誤章節）
2	validate-version-sync.sh	7 個平台入口文件（SKILL.md、AGENTS.md、GEMINI.md 等）版本號是否完全一致