taiwan-payment-skill 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +130 -197
  2. package/assets/taiwan-payment/CLAUDE.md +4 -1
  3. package/assets/taiwan-payment/EXAMPLES.md +48 -0
  4. package/assets/taiwan-payment/README.md +23 -7
  5. package/assets/taiwan-payment/SKILL.md +29 -2
  6. package/assets/taiwan-payment/data/error-codes.csv +60 -32
  7. package/assets/taiwan-payment/data/operations.csv +9 -0
  8. package/assets/taiwan-payment/data/providers.csv +3 -0
  9. package/assets/taiwan-payment/examples/ezpay-payment-example.py +690 -690
  10. package/assets/taiwan-payment/examples/linepay-payment-example.py +305 -0
  11. package/assets/taiwan-payment/examples/paynow-payment-example.py +767 -767
  12. package/assets/taiwan-payment/examples/pchomepay-payment-example.py +556 -556
  13. package/assets/taiwan-payment/examples/shopline-payment-example.py +291 -0
  14. package/assets/taiwan-payment/examples/smilepay-payment-example.py +673 -673
  15. package/assets/taiwan-payment/examples/tappay-payment-example.py +337 -0
  16. package/assets/taiwan-payment/references/ezpay-payment-api.md +660 -660
  17. package/assets/taiwan-payment/references/linepay-payment-api.md +940 -0
  18. package/assets/taiwan-payment/references/paynow-payment-api.md +1654 -1654
  19. package/assets/taiwan-payment/references/pchomepay-payment-api.md +1431 -1431
  20. package/assets/taiwan-payment/references/shopline-payment-api.md +1523 -0
  21. package/assets/taiwan-payment/references/smilepay-payment-api.md +919 -919
  22. package/assets/taiwan-payment/references/tappay-payment-api.md +1245 -0
  23. package/assets/templates/base/skill-content.md +27 -0
  24. package/assets/templates/platforms/agent.json +2 -2
  25. package/assets/templates/platforms/antigravity.json +1 -1
  26. package/assets/templates/platforms/claude.json +2 -2
  27. package/assets/templates/platforms/codebuddy.json +2 -2
  28. package/assets/templates/platforms/codex.json +2 -2
  29. package/assets/templates/platforms/continue.json +2 -2
  30. package/assets/templates/platforms/copilot.json +2 -2
  31. package/assets/templates/platforms/cursor.json +2 -2
  32. package/assets/templates/platforms/gemini.json +2 -2
  33. package/assets/templates/platforms/kiro.json +2 -2
  34. package/assets/templates/platforms/opencode.json +2 -2
  35. package/assets/templates/platforms/qoder.json +2 -2
  36. package/assets/templates/platforms/roocode.json +2 -2
  37. package/assets/templates/platforms/trae.json +2 -2
  38. package/assets/templates/platforms/windsurf.json +2 -2
  39. package/package.json +5 -2
package/README.md CHANGED
@@ -1,197 +1,130 @@
1
- <h1 align="center">taiwan-payment-skill</h1>
2
-
3
- <h3 align="center">台灣金流 AI 開發技能包</h3>
4
-
5
- <p align="center">
6
- <strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi 統一</strong>
7
- </p>
8
-
9
- <p align="center">
10
- <a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/v/taiwan-payment-skill?style=flat-square&logo=npm" alt="npm version"></a>
11
- <a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/dm/taiwan-payment-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
12
- <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js">
13
- <img src="https://img.shields.io/badge/platforms-14-blue?style=flat-square" alt="14 Platforms">
14
- <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
15
- </p>
16
-
17
- <p align="center">
18
- <a href="https://paypal.me/cccsubcom"><img src="https://img.shields.io/badge/PayPal-支持開發-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal"></a>
19
- </p>
20
-
21
- ---
22
-
23
- ## 安裝
24
-
25
- ```bash
26
- npm install -g taiwan-payment-skill
27
- ```
28
-
29
- ---
30
-
31
- ## 使用方式
32
-
33
- ```bash
34
- # 進入專案目錄
35
- cd /path/to/your/project
36
-
37
- # 選擇你的 AI 助手
38
- taiwan-payment init --ai claude # Claude Code
39
- taiwan-payment init --ai cursor # Cursor
40
- taiwan-payment init --ai windsurf # Windsurf
41
- taiwan-payment init --ai copilot # GitHub Copilot
42
- taiwan-payment init --ai antigravity # Antigravity
43
- taiwan-payment init --ai all # 全部安裝
44
- ```
45
-
46
- <details>
47
- <summary>完整平台列表</summary>
48
-
49
- ```bash
50
- taiwan-payment init --ai kiro # Kiro (AWS)
51
- taiwan-payment init --ai codex # Codex CLI (OpenAI)
52
- taiwan-payment init --ai qoder # Qoder
53
- taiwan-payment init --ai roocode # Roo Code
54
- taiwan-payment init --ai gemini # Gemini CLI
55
- taiwan-payment init --ai trae # Trae (ByteDance)
56
- taiwan-payment init --ai opencode # OpenCode
57
- taiwan-payment init --ai continue # Continue
58
- taiwan-payment init --ai codebuddy # CodeBuddy (Tencent)
59
- ```
60
-
61
- </details>
62
-
63
- ---
64
-
65
- ## 其他指令
66
-
67
- ```bash
68
- taiwan-payment list # 列出支援平台
69
- taiwan-payment info # 顯示技能資訊
70
- taiwan-payment versions # 列出可用版本
71
- taiwan-payment update # 檢查更新
72
- ```
73
-
74
- ### 選項
75
-
76
- ```bash
77
- taiwan-payment init --force # 覆蓋現有檔案
78
- taiwan-payment init --global # 安裝到全域目錄(所有專案共用)
79
- ```
80
-
81
- ### 全域安裝
82
-
83
- 使用 `--global` 可將技能安裝到使用者目錄,讓所有專案都能使用:
84
-
85
- ```bash
86
- taiwan-payment init --ai cursor --global # ~/.cursor/skills/taiwan-payment/
87
- taiwan-payment init --ai claude --global # ~/.claude/skills/taiwan-payment/
88
- taiwan-payment init --ai antigravity --global # ~/.gemini/antigravity/global_skills/taiwan-payment/
89
- ```
90
-
91
- ---
92
-
93
- ## 支援平台
94
-
95
- | 平台 | 說明 | 啟動方式 |
96
- |------|------|----------|
97
- | **Claude Code** | Anthropic 官方 CLI | `/taiwan-payment` |
98
- | **Cursor** | AI 程式編輯器 | `/taiwan-payment` |
99
- | **Windsurf** | Codeium 編輯器 | 自動 |
100
- | **Copilot** | GitHub Copilot | `/taiwan-payment` |
101
- | **Antigravity** | Google AI 助手 | `/taiwan-payment` |
102
- | **Kiro** | AWS AI 助手 | `/taiwan-payment` |
103
- | **Codex** | OpenAI CLI | 自動 |
104
- | **Qoder** | Qodo AI 助手 | 自動 |
105
- | **RooCode** | VSCode 擴充 | `/taiwan-payment` |
106
- | **Gemini CLI** | Google Gemini | 自動 |
107
- | **Trae** | ByteDance AI | 自動 |
108
- | **OpenCode** | 開源 AI 助手 | 自動 |
109
- | **Continue** | 開源 AI 助手 | 自動 |
110
- | **CodeBuddy** | Tencent AI | 自動 |
111
-
112
- ---
113
-
114
- ## 金流服務商
115
-
116
- | 服務商 | 加密方式 | API 風格 | 特點 |
117
- |--------|---------|---------|------|
118
- | **ECPay 綠界** | URL Encode + SHA256 | Form POST | 市佔率最高,穩定性佳 |
119
- | **NewebPay 藍新** | AES-256-CBC + SHA256 | Form POST + AES | 支援最多支付方式 (13 種) |
120
- | **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON | RESTful 設計,API 現代化 |
121
-
122
- ---
123
-
124
- ## 付款方式支援
125
-
126
- ### 信用卡支付
127
- - 一次付清、分期付款 (3/6/12/18/24 期)
128
- - 信用卡定期定額、信用卡記憶
129
-
130
- ### 電子錢包
131
- - Apple Pay、Google Pay、Samsung Pay
132
- - LINE Pay、台灣 Pay
133
-
134
- ### 轉帳支付
135
- - 網路 ATM、ATM 虛擬帳號
136
-
137
- ### 超商支付
138
- - 超商代碼、超商條碼
139
-
140
- ### 其他
141
- - TWQR、BNPL 無卡分期、AFTEE 先享後付
142
-
143
- ---
144
-
145
- ## 智能工具
146
-
147
- 安裝後包含以下 Python 工具(純 Python,無需外部依賴):
148
-
149
- ```bash
150
- # BM25 搜索引擎 - 搜索錯誤碼、欄位映射、付款方式
151
- python scripts/search.py "10100058" --domain error
152
- python scripts/search.py "信用卡" --domain payment_method
153
- python scripts/search.py "CheckMacValue" --domain troubleshoot
154
-
155
- # 智能推薦系統 - 根據需求推薦金流服務商
156
- python scripts/recommend.py "高交易量 電商 穩定"
157
- python scripts/recommend.py "多元支付 LINE Pay Apple Pay"
158
-
159
- # 連線測試工具 - 測試 API 連線
160
- python scripts/test_payment.py ecpay
161
- python scripts/test_payment.py all
162
- ```
163
-
164
- ### 搜索域
165
-
166
- - `provider` - 服務商比較
167
- - `operation` - API 操作端點
168
- - `error` - 錯誤碼查詢
169
- - `field` - 欄位映射
170
- - `payment_method` - 付款方式
171
- - `troubleshoot` - 疑難排解
172
- - `reasoning` - 推薦決策規則
173
-
174
- ---
175
-
176
- ## 功能特色
177
-
178
- - 完整 API 文檔 (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow)
179
- - BM25 搜索引擎
180
- - 智能推薦系統
181
- - 9 組完整代碼範例 (TypeScript/Python)
182
- - 7 個 CSV 數據檔 (易於維護)
183
- - 加密實作指南 (SHA256, AES-CBC, AES-GCM)
184
- - 16 個疑難排解案例
185
-
186
- ---
187
-
188
- ## 授權
189
-
190
- [MIT License](https://github.com/Moksa1123/taiwan-payment/blob/main/LICENSE)
191
-
192
- ---
193
-
194
- <p align="center">
195
- <sub>Made by <strong>Moksa</strong></sub><br>
196
- <sub>service@moksaweb.com</sub>
197
- </p>
1
+ <h1 align="center">taiwan-payment-skill</h1>
2
+
3
+ <h3 align="center">台灣金流 AI 開發技能包</h3>
4
+
5
+ <p align="center">
6
+ <strong>10 大金流平台一次串接</strong>
7
+ </p>
8
+
9
+ <p align="center">
10
+ ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · ezPay · PayNow · Shopline · LINE Pay · TapPay
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/v/taiwan-payment-skill?style=flat-square&logo=npm" alt="npm version"></a>
15
+ <a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/dm/taiwan-payment-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
16
+ <img src="https://img.shields.io/badge/providers-10-success?style=flat-square" alt="10 Providers">
17
+ <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
18
+ <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <a href="https://paypal.me/cccsubcom"><img src="https://img.shields.io/badge/PayPal-支持開發-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal"></a>
23
+ </p>
24
+
25
+ ---
26
+
27
+ ## 安裝
28
+
29
+ ```bash
30
+ npm install -g taiwan-payment-skill
31
+ ```
32
+
33
+ ## 快速開始
34
+
35
+ ```bash
36
+ cd /path/to/your/project
37
+
38
+ taiwan-payment init # 互動式
39
+ taiwan-payment init --ai claude # Claude Code
40
+ taiwan-payment init --ai cursor # Cursor
41
+ taiwan-payment init --ai windsurf # Windsurf
42
+ taiwan-payment init --ai all # 全部安裝
43
+ ```
44
+
45
+ 安裝完後,AI 助手裡用自然語言:
46
+
47
+ ```
48
+ 建立 ECPay 信用卡付款訂單,金額 2500 元
49
+ NewebPay MPG 整合 LINE Pay + Apple Pay
50
+ PChomePay 拍錢包訂單,5% P 幣回饋
51
+ PayNow PaymentIntent,啟用 LINE Pay 線上+線下扣款
52
+ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動扣款
53
+ ```
54
+
55
+ ---
56
+
57
+ ## 10 家金流平台
58
+
59
+ | 服務商 | 加密 / 認證 | 特色 |
60
+ |---|---|---|
61
+ | **ECPay 綠界** | SHA256 CheckMacValue | 市佔率最高、文檔最完整 |
62
+ | **NewebPay 藍新** | AES-256-CBC + SHA256 | MPG 整合、信用卡記憶、13 種支付 |
63
+ | **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON、AFTEE、iCash |
64
+ | **SmilePay 速買配** | Verify_key + 加權檢核碼 | 無 AES、ibon / FamiPort 直接打單 |
65
+ | **PChomePay 拍錢包** | Basic Auth → 8h pcpay-token | PChome 生態、5% P 幣回饋、金物流二合一 |
66
+ | **ezPay 簡單付** | 同 NewebPay (AES-256-CBC) | 藍新小型商家品牌、低門檻 |
67
+ | **PayNow 立吉富** | JWT Bearer (現代) / 動態 AES-256 (傳統) | 雙 API、Stripe-like、Apple Pay 完整 |
68
+ | **Shopline Payments** | merchantId + apiKey | 金額以分為單位、HMAC-SHA256 webhook |
69
+ | **LINE Pay v4** | Channel ID/Secret + HMAC-SHA256 + Nonce | Request→Confirm 兩段、Preapproved Pay |
70
+ | **TapPay** | Partner Key (Header) | PCI 隔離、Prime 兩段式、Card Token |
71
+
72
+ 每家附完整 Python 範例 + 反推的加密實作 + 錯誤碼對照 + 測試帳號。
73
+
74
+ ## 技能包內容
75
+
76
+ ```
77
+ taiwan-payment/
78
+ ├── SKILL.md # AI 技能主文檔
79
+ ├── EXAMPLES.md # 實戰範例集
80
+ ├── references/ # 10 份 API 規格 (~9,200 行)
81
+ │ ├── ecpay-payment-api.md
82
+ │ ├── newebpay-payment-api.md
83
+ │ ├── payuni-payment-api.md
84
+ │ ├── smilepay-payment-api.md # 反推 Mid_smilepay 加權檢核碼
85
+ │ ├── pchomepay-payment-api.md # 含 8h token 流程
86
+ │ ├── ezpay-payment-api.md # diff vs Newebpay
87
+ │ ├── paynow-payment-api.md # 雙 API 並行
88
+ │ ├── shopline-payment-api.md # Redirect + Embedded
89
+ │ ├── linepay-payment-api.md # HMAC + Preapproved
90
+ │ └── tappay-payment-api.md # Prime + Token 重複扣款
91
+ ├── examples/ # 10 個生產級 Python 範例
92
+ └── data/ # 7 份 CSV
93
+ ├── providers.csv # 10 服務商完整比較
94
+ ├── operations.csv # 26 個 API 操作
95
+ ├── payment-methods.csv # 25+ 支付方式對照
96
+ ├── error-codes.csv # 130+ 錯誤碼
97
+ └── ...
98
+ ```
99
+
100
+ ## CLI 指令
101
+
102
+ ```bash
103
+ taiwan-payment list # 列出 AI 平台
104
+ taiwan-payment info # 技能資訊
105
+ taiwan-payment update # 檢查更新
106
+ taiwan-payment init --force # 覆蓋安裝
107
+ taiwan-payment init --global # 全域安裝
108
+ ```
109
+
110
+ ## 14 個 AI 平台支援
111
+
112
+ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
113
+
114
+ ## 相關套件
115
+
116
+ 本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
117
+
118
+ - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 5 家電子發票
119
+ - [taiwan-logistics-skill](https://www.npmjs.com/package/taiwan-logistics-skill) — 7 家物流(含 HCT 直連)
120
+
121
+ ## 授權
122
+
123
+ [MIT License](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE)
124
+
125
+ ---
126
+
127
+ <p align="center">
128
+ <sub>Made by <strong>Moksa</strong></sub><br>
129
+ <sub>service@moksaweb.com</sub>
130
+ </p>
@@ -36,7 +36,10 @@ taiwan-payment/ # Source of Truth
36
36
  │ ├── smilepay-payment-api.md
37
37
  │ ├── pchomepay-payment-api.md
38
38
  │ ├── ezpay-payment-api.md
39
- │ └── paynow-payment-api.md
39
+ │ ├── paynow-payment-api.md
40
+ │ ├── shopline-payment-api.md
41
+ │ ├── linepay-payment-api.md
42
+ │ └── tappay-payment-api.md
40
43
  ├── scripts/ # Utility scripts
41
44
  │ ├── core.py # BM25 search engine
42
45
  │ ├── recommend.py # Recommendation system
@@ -1491,4 +1491,52 @@ PayNow 有**兩代 API 並行**:
1491
1491
 
1492
1492
  ---
1493
1493
 
1494
+ ## Shopline Payments 範例
1495
+
1496
+ Shopline Payments (SLP) 採 **HTTP Header `merchantId` + `apiKey`** 認證,所有金額以**分**為單位(NT$1000 = 100000)。提供 Redirect 與 Embedded SDK 雙模式,Webhook 用 HMAC-SHA256 驗章。
1497
+
1498
+ ### 完整 Python 範例
1499
+ 請見 [`examples/shopline-payment-example.py`](examples/shopline-payment-example.py) — 涵蓋 sessions/create / sessionQuery / refund / Webhook 驗章。
1500
+
1501
+ ### 三大要點
1502
+
1503
+ 1. **金額是分(cents)**:NT$1,050 要傳 `value: 105000`,弄錯會差 100 倍。
1504
+ 2. **僅支援 TWD**:`currency` 固定為 `TWD`;其他幣別不支援。
1505
+ 3. **Webhook 驗章**:`x-slp-signature: sha256=<hex>` header,HMAC-SHA256 用 `webhookSecret` 對 raw body 簽。**用 raw bytes,不要 parse JSON 後再 stringify**(會差換行/空白)。
1506
+
1507
+ ---
1508
+
1509
+ ## LINE Pay v4 範例
1510
+
1511
+ LINE Pay 採 **兩段式流程**:`Request → Confirm`。每次請求需產生 Nonce + HMAC-SHA256 簽章。
1512
+
1513
+ ### 完整 Python 範例
1514
+ 請見 [`examples/linepay-payment-example.py`](examples/linepay-payment-example.py) — 涵蓋 Request / Confirm / Capture / Void / Refund / Preapproved Pay (自動扣款)。
1515
+
1516
+ ### 五大要點
1517
+
1518
+ 1. **HMAC string-to-sign 公式(v3 慣例)**:`ChannelSecret + ApiPath + Body + Nonce` (POST) / `ChannelSecret + ApiPath + QueryString + Nonce` (GET)。⚠️ v4 公式與 v3 是否完全一致需以官方 PDF 驗證。
1519
+ 2. **transactionId 是 19 位數字**:在 JS 直接用 number 會被 IEEE-754 截斷,**永遠用字串處理**。
1520
+ 3. **Confirm 的 amount/currency 必須與 Request 完全一致**:差一塊錢就 1183 錯誤。
1521
+ 4. **Capture 兩階段授權**:建立時 `options.payment.capture=false` 只授權;之後手動呼叫 `/capture` 請款,可分批請款多次。
1522
+ 5. **Preapproved Pay 自動扣款**:建立時帶 `payType=PREAPPROVED` 取得 `regKey`,之後用 `/preapprovedPay/{regKey}/payment` 直接扣款,免使用者再次確認。
1523
+
1524
+ ---
1525
+
1526
+ ## TapPay 範例
1527
+
1528
+ TapPay 是 **PCI 隔離設計**:前端 SDK 取 Prime(60 秒 TTL)→ 後端用 Prime 呼叫 pay-by-prime。商家從不接觸卡號。
1529
+
1530
+ ### 完整 Python 範例
1531
+ 請見 [`examples/tappay-payment-example.py`](examples/tappay-payment-example.py) — 涵蓋 pay-by-prime / pay-by-card-token (重複扣款) / refund / query / remove-card。
1532
+
1533
+ ### 四大要點
1534
+
1535
+ 1. **三段式金鑰**:`Partner Key` (後端密鑰) / `App Key` (前端 SDK 公鑰) / `Merchant ID`。**Partner Key 絕對不可放前端**。
1536
+ 2. **Prime 是 60 秒一次性 token**:前端取 Prime 後要立刻送後端付款;過期或重用會 status=3。
1537
+ 3. **重複扣款**:`pay-by-prime` 帶 `remember=true` 後,回應內 `card_secret` 含 `card_key + card_token`,存起來下次直接 `pay-by-card-token`,免再過 SDK。適合訂閱與快速結帳。
1538
+ 4. **status=0 才是成功**:別只看 HTTP 200;TapPay HTTP 200 但 status≠0 是業務失敗。
1539
+
1540
+ ---
1541
+
1494
1542
  **更多範例持續更新中...**
@@ -3,7 +3,7 @@
3
3
  <h3 align="center">台灣金流 AI 開發技能包</h3>
4
4
 
5
5
  <p align="center">
6
- <strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi 統一</strong>
6
+ <strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi 統一 · SmilePay 速買配 · PChomePay 拍錢包 · ezPay 簡單付 · PayNow 立吉富</strong>
7
7
  </p>
8
8
 
9
9
  <p align="center">
@@ -22,10 +22,12 @@
22
22
 
23
23
  ## 專案簡介
24
24
 
25
- Taiwan Payment Skill 是專為台灣金流整合設計的 AI 開發工具包,支援七大金流平台 (ECPay、NewebPay、PAYUNi) 的完整 API 整合。本工具包提供企業級程式碼範例、BM25 智能搜尋引擎、服務商推薦系統與代碼生成器,協助開發團隊快速完成金流系統整合。
25
+ Taiwan Payment Skill 是專為台灣金流整合設計的 AI 開發工具包,支援十大金流平台(ECPay 綠界、NewebPay 藍新、PAYUNi 統一、SmilePay 速買配、PChomePay 拍錢包、ezPay 簡單付、PayNow 立吉富)的完整 API 整合。本工具包提供企業級程式碼範例、BM25 智能搜尋引擎、服務商推薦系統與代碼生成器,協助開發團隊快速完成金流系統整合。
26
26
 
27
- **版本:** 1.1.3
27
+ **版本:** 1.3.0
28
28
  **狀態:** Production Ready
29
+ **v1.3.0 新增:** Shopline Payments / LINE Pay v4 / TapPay 3 家金流服務商完整支援
30
+ **v1.2.0:** SmilePay / PChomePay / ezPay / PayNow 4 家金流服務商完整支援
29
31
 
30
32
  ---
31
33
 
@@ -40,13 +42,20 @@ Taiwan Payment Skill 是專為台灣金流整合設計的 AI 開發工具包,
40
42
  - **嚴謹錯誤處理** - 完整的例外處理與中文錯誤訊息
41
43
  - **實戰測試憑證** - 包含測試環境憑證,可直接執行驗證
42
44
 
43
- ### 生產級 Python 範例 (3 個)
45
+ ### 生產級 Python 範例 (10 個)
44
46
 
45
47
  完整的金流整合實作,支援多種付款方式:
46
48
 
47
- - **ecpay-payment-example.py** - ECPay 金流整合
48
- - **newebpay-payment-example.py** - NewebPay MPG 整合
49
- - **payuni-payment-example.py** - PAYUNi 統一金流
49
+ - **ecpay-payment-example.py** - ECPay 金流整合(信用卡 / ATM / 超商代碼 / 超商條碼)
50
+ - **newebpay-payment-example.py** - NewebPay MPG 整合(含 LINE Pay / Apple Pay / Google Pay)
51
+ - **payuni-payment-example.py** - PAYUNi 統一金流(AES-256-GCM、AFTEE、iCash)
52
+ - **smilepay-payment-example.py** - SmilePay 整合(ATM / Barcode / ibon / FamiPort / 聯合信用卡 / 信用卡分期)
53
+ - **pchomepay-payment-example.py** - PChomePay 整合(Basic Auth → pcpay-token 兩階段認證 + 拍錢包 5% P 幣回饋)
54
+ - **ezpay-payment-example.py** - ezPay 簡單付整合(與 NewebPay 共用 MPG 加密;diff 文件)
55
+ - **paynow-payment-example.py** - PayNow 立吉富整合(現代 PaymentIntent + 傳統 cashflow 雙 API)
56
+ - **shopline-payment-example.py** - Shopline Payments 整合(Redirect / Embedded SDK / HMAC-SHA256 Webhook)
57
+ - **linepay-payment-example.py** - LINE Pay v4 整合(Request → Confirm 兩段式 + Capture/Void + Preapproved Pay)
58
+ - **tappay-payment-example.py** - TapPay 整合(Prime 兩段式 / pay-by-card-token 重複扣款 / PCI 隔離)
50
59
 
51
60
  ### BM25 智能搜尋引擎
52
61
 
@@ -165,6 +174,13 @@ taiwan-payment init --ai claude --global
165
174
  | **ECPay 綠界** | SHA256 CheckMacValue | Form POST | 信用卡、ATM、超商代碼、超商條碼 |
166
175
  | **NewebPay 藍新** | AES-256-CBC + SHA256 | Form POST + AES | 信用卡、ATM、超商、LINE Pay、Apple Pay (13 種) |
167
176
  | **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON | 信用卡、ATM、超商、AFTEE、iCash Pay |
177
+ | **SmilePay 速買配** | Verify_key + Mid_smilepay 加權檢核碼 | Form POST + XML 回應 | ATM、Barcode、ibon、FamiPort、信用卡、信用卡分期、聯合信用卡 |
178
+ | **PChomePay 拍錢包** | HTTP Basic Auth → pcpay-token | RESTful JSON | 信用卡(含分期)、ATM 虛擬帳號、超商代碼、拍錢包(5% P 幣回饋)、超商取貨付款 |
179
+ | **ezPay 簡單付** | 同 NewebPay (AES-256-CBC + SHA256) | Form POST + AES | 信用卡、ATM、超商、跨境支付寶/微信(與 NewebPay 同集團) |
180
+ | **PayNow 立吉富** | JWT Bearer (現代) / 動態 AES-256 (傳統) | RESTful JSON / Form POST | 信用卡、ATM、超商代碼、Apple Pay (含延遲扣款)、LINE Pay 線上+線下 |
181
+ | **Shopline Payments** | merchantId + apiKey HTTP Header | RESTful JSON | 信用卡、Apple Pay、LINE Pay、街口、ATM、中租 BNPL(金額以分為單位) |
182
+ | **LINE Pay v4** | Channel ID + ChannelSecret + HMAC-SHA256 Nonce | RESTful JSON | LINE 生態系直連、Request→Confirm 兩段式、Preapproved Pay 自動扣款、跨國 |
183
+ | **TapPay** | Partner Key + App Key + Merchant ID(Prime 兩段式) | RESTful JSON | 信用卡、Apple Pay、Google Pay、LINE Pay、Virtual Account;PCI 隔離設計 |
168
184
 
169
185
  ---
170
186
 
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: taiwan-payment
3
- description: Taiwan Payment API integration specialist for ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, and PayNow payment gateways. Use when developing payment systems, implementing credit card, ATM, CVS, e-wallet, or LINE Pay/Apple Pay payments, or working with Taiwan payment gateway APIs. Handles encryption (SHA256, AES-256-CBC, AES-256-GCM, dynamic AES-256, JWT, Basic Auth → token), API requests, and service provider differences.
3
+ description: Taiwan Payment API integration specialist for ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay v4, and TapPay payment gateways. Use when developing payment systems, implementing credit card, ATM, CVS, e-wallet, LINE Pay, Apple Pay, Google Pay, or BNPL payments, or working with Taiwan payment gateway APIs. Handles encryption (SHA256, AES-256-CBC, AES-256-GCM, dynamic AES-256, JWT, HMAC-SHA256, Basic Auth → token, Prime token), API requests, and service provider differences.
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
7
  # Taiwan Payment Development Skill
8
8
 
9
- > 此技能涵蓋台灣金流 API 整合開發,包含綠界科技 (ECPay)、藍新金流 (NewebPay)、統一金流 (PAYUNi)、速買配 (SmilePay)、拍錢包 (PChomePay)、ezPay 簡單付、立吉富 (PayNow) 七家服務商。
9
+ > 此技能涵蓋台灣金流 API 整合開發,包含綠界 (ECPay)、藍新 (NewebPay)、統一 (PAYUNi)、速買配 (SmilePay)、拍錢包 (PChomePay)、ezPay 簡單付、立吉富 (PayNow)、SHOPLINE Payments、LINE Pay v4、TapPay 共十家服務商。
10
10
 
11
11
  ## 快速導覽
12
12
 
@@ -19,6 +19,9 @@ user-invocable: true
19
19
  - `references/pchomepay-payment-api.md` - 拍錢包 API 規格(含 Basic Auth → Token 兩階段認證)
20
20
  - `references/ezpay-payment-api.md` - ezPay 簡單付 API 規格(與藍新 Newebpay 同集團、同加密)
21
21
  - `references/paynow-payment-api.md` - 立吉富 API 規格(傳統版 cashflow + 現代版 PaymentIntent 雙 API)
22
+ - `references/shopline-payment-api.md` - Shopline Payments API 規格(Redirect + Embedded SDK 雙模式)
23
+ - `references/linepay-payment-api.md` - LINE Pay v4 API 規格(HMAC-SHA256 + Preapproved Pay)
24
+ - `references/tappay-payment-api.md` - TapPay API 規格(Prime 兩段式 / PCI 隔離 / pay-by-token 重複扣款)
22
25
  - [EXAMPLES.md](EXAMPLES.md) - 程式碼範例集
23
26
 
24
27
  ### 智能工具
@@ -114,6 +117,9 @@ python scripts/recommend.py "會員制 定期扣款" --format simple
114
117
  - **PChomePay**: 拍錢包、PChome、P 幣、Basic Auth、Token、虛擬帳號、超商代碼條碼、物流二合一
115
118
  - **ezPay**: 簡單付、藍新小型、低門檻、跨境、智冠、支付寶、微信
116
119
  - **PayNow**: 立吉富、Apple Pay、PaymentIntent、Stripe-like、JWT、票券、mPOS、現代+傳統雙 API
120
+ - **Shopline**: SHOPLINE 商店、Redirect、Embedded SDK、街口、中租 BNPL、cents、HMAC-SHA256
121
+ - **LINE Pay**: LINE、自動扣款、Preapproved、Capture、Void、跨國、Channel Secret、Nonce
122
+ - **TapPay**: PCI 隔離、Prime、自製結帳頁、card_secret、CherryTech、Apple Pay、Google Pay
117
123
 
118
124
  **反模式警告:**
119
125
  推薦系統會自動提示不建議的場景:
@@ -124,6 +130,9 @@ python scripts/recommend.py "會員制 定期扣款" --format simple
124
130
  - PChomePay: 不在 PChome 生態系
125
131
  - ezPay: 大型商家、需要分期、需要完整支付方式
126
132
  - PayNow: 簡單需求(雙 API 學習成本高)
133
+ - Shopline: 不在 SHOPLINE 商店生態
134
+ - LINE Pay: 主要客戶不用 LINE
135
+ - TapPay: 不想自製結帳頁、無前端能力
127
136
 
128
137
  ### 付款測試工具 (test_payment.py)
129
138
 
@@ -246,6 +255,24 @@ python scripts/test_payment.py all
246
255
  - **傳輸**: 傳統用 Form POST;現代用 application/json
247
256
  - **特色**: 13 種付款方式(含 LINE Pay 線上線下、Apple Pay v1/v2、Apple Pay Deferred 延遲扣款)、Customer / Card Token 會員記憶、`webhookUrl` 推送回呼。**新專案應優先採用現代版 PaymentIntent**
248
257
 
258
+ ### Shopline Payments 特性
259
+ - **優勢**: SHOPLINE 集團官方金流、RESTful JSON 設計、Redirect + Embedded SDK 雙模式
260
+ - **認證**: HTTP Header 帶 `merchantId` + `apiKey`;Webhook 用 HMAC-SHA256
261
+ - **傳輸**: application/json,金額以**分**為單位 (1 TWD = 100),僅支援 TWD
262
+ - **特色**: Embedded SDK 適合自訂 UI 與 PCI 隔離;Redirect 模式快速上線;6 種主流支付(信用卡/Apple Pay/LINE Pay/街口/ATM/中租 BNPL)
263
+
264
+ ### LINE Pay 特性
265
+ - **優勢**: LINE 生態系直連、跨國(TW/JP/TH/TW)、自動扣款(Preapproved Pay)、Capture/Void 雙階段授權
266
+ - **認證**: Channel ID + Channel Secret;每次請求需產生 Nonce 並用 HMAC-SHA256 簽章 (`X-LINE-Authorization`)
267
+ - **傳輸**: RESTful JSON v4 規格
268
+ - **特色**: Request → Confirm 兩段式流程;Capture 可手動請款(autoCapture=false);19 位 transactionId(JS 需用字串避免精度遺失);不支援 Apple Pay / Google Pay(這是 LINE Pay 自身就是支付工具)
269
+
270
+ ### TapPay 特性
271
+ - **優勢**: PCI 隔離設計(前端 SDK 取 Prime → 後端付款)、支援多元電子錢包(Apple Pay / Google Pay / LINE Pay / 街口)、適合自製結帳頁
272
+ - **認證**: Partner Key(後端)+ App Key(前端)+ Merchant ID 三段式金鑰;Prime 60 秒過期
273
+ - **傳輸**: RESTful JSON
274
+ - **特色**: 兩段式架構 (Prime → pay-by-prime);`card_secret` 機制可記憶卡片做重複扣款 (pay-by-token);`result_url` 雙網址回調;無自家結帳頁,UI 完全在商家自管
275
+
249
276
  ## 開發實作步驟
250
277
 
251
278
  ### 1. 服務實作架構
@@ -40,35 +40,63 @@ payuni,API_TIMEOUT,API 請求逾時,API Timeout,system,error,重新交易
40
40
  payuni,PAYMENT_FAILED,付款失敗,Payment Failed,payment,error,稍後重試或使用其他支付方式
41
41
  payuni,INVALID_PAYMENT_TYPE,不支援的支付方式,Unsupported Payment Type,validation,error,使用支援的支付方式
42
42
  payuni,JSON_PARSE_ERROR,JSON 解析失敗,JSON Parse Error,system,error,檢查 API 回應格式
43
- smilepay,1,交易成功,Success,success,info,
44
- smilepay,-1,參數錯誤,Parameter error,validation,error,檢查必填欄位 Dcvc/Rvg2c/Verify_key
45
- smilepay,-2,商家驗證失敗,Merchant verification failed,auth,error,確認 Verify_key 與 mid 正確
46
- smilepay,-3,簽章/檢核碼不正確,Signature mismatch,auth,error,通知時驗證 Mid_smilepay 加權檢核碼
47
- smilepay,-10,Pay_zg 不支援,Unsupported payment type,validation,error,改用支援的 Pay_zg 值 (1/2/3/4/6/11)
48
- smilepay,-15,訂單金額異常,Amount invalid,validation,error,Amount 必須為正整數
49
- smilepay,-20,訂單編號重複,Duplicate Data_id,validation,error,使用唯一 Data_id
50
- smilepay,-23,逾期訂單/訂單已關閉,Order expired,validation,error,檢查 Deadline_date 設定
51
- pchomepay,10001,APP ID 或 SECRET 錯誤,Invalid Basic Auth credentials,auth,error,檢查 APP ID 與 SECRET 是否正確 base64 編碼
52
- pchomepay,10003,Token 已過期,Token expired,auth,error,重新呼叫 POST /v1/token 取得新 token
53
- pchomepay,10004,Token 不存在,Token not found,auth,error,header 必須帶 pcpay-token
54
- pchomepay,10005,IP 不在白名單,IP not whitelisted,auth,error,將呼叫端 IP 加入後台白名單
55
- pchomepay,20001,訂單已存在,Duplicate order_id,validation,error,使用唯一 order_id
56
- pchomepay,20002,訂單金額錯誤,Invalid amount,validation,error,amount 必須為正整數
57
- pchomepay,30001,退款金額超過原訂單,Refund exceeds original,refund,error,退款金額 + 退款手續費需小於原訂單
58
- pchomepay,30002,餘額不足,Insufficient balance,refund,error,商家代收帳戶餘額不足以扣除退款 + 手續費
59
- pchomepay,40001,卡號驗證失敗,Card validation failed,payment,error,信用卡資料錯誤;於 sandbox 改用測試卡號
60
- pchomepay,90001,超商取貨建立失敗,CVS COD creation failed,logistics,error,參見 taiwan-logistics 文件確認物流欄位
61
- ezpay,KEY10001,商店代號錯誤,Invalid MerchantID,auth,error,確認 MerchantID 與後台一致
62
- ezpay,KEY10002,簽章驗證失敗,TradeSha mismatch,auth,error,SHA256 計算需含 HashKey/HashIV 且大寫
63
- ezpay,KEY10003,加密資料解密失敗,TradeInfo decrypt failed,auth,error,確認 AES-256-CBC + Hex + PKCS7 與 32-char HashKey 16-char HashIV
64
- ezpay,MEM10001,商家未啟用該付款方式,Method not enabled,validation,error,於 ezPay 後台啟用該付款方式
65
- ezpay,MPG10001,訂單編號重複,Duplicate MerchantOrderNo,validation,error,使用唯一訂單編號
66
- ezpay,VACC10001,虛擬帳號逾期,VACC expired,validation,error,檢查 ExpireDate 設定
67
- paynow,M001,商家代號錯誤,Invalid Merchant,auth,error,確認商家代號正確
68
- paynow,A001,加密驗證失敗,Encryption validation failed,auth,error,傳統版檢查 GP/GK 動態金鑰;現代版檢查 JWT Bearer
69
- paynow,B001,訂單金額錯誤,Invalid Amount,validation,error,確認 amount 為正整數且小於 1,000,000,000,000
70
- paynow,C001,訂單編號重複,Duplicate paymentNo,validation,error,使用唯一 paymentNo (現代版可省略由系統產生)
71
- paynow,P001,信用卡授權失敗,Card authorization failed,payment,error,改用其他卡或聯繫銀行
72
- paynow,Q001,Token 過期,JWT expired,auth,error,重新申請 JWT Bearer Token
73
- paynow,R001,退款超過原訂單,Refund exceeds original,refund,error,確認可退金額
74
- paynow,T001,信用卡 token 不存在,Card token not found,payment,error,確認 customer 與 card token 仍有效
43
+ smilepay,1,交易成功,Success,success,info,
44
+ smilepay,-1,參數錯誤,Parameter error,validation,error,檢查必填欄位 Dcvc/Rvg2c/Verify_key
45
+ smilepay,-2,商家驗證失敗,Merchant verification failed,auth,error,確認 Verify_key 與 mid 正確
46
+ smilepay,-3,簽章/檢核碼不正確,Signature mismatch,auth,error,通知時驗證 Mid_smilepay 加權檢核碼
47
+ smilepay,-10,Pay_zg 不支援,Unsupported payment type,validation,error,改用支援的 Pay_zg 值 (1/2/3/4/6/11)
48
+ smilepay,-15,訂單金額異常,Amount invalid,validation,error,Amount 必須為正整數
49
+ smilepay,-20,訂單編號重複,Duplicate Data_id,validation,error,使用唯一 Data_id
50
+ smilepay,-23,逾期訂單/訂單已關閉,Order expired,validation,error,檢查 Deadline_date 設定
51
+ pchomepay,10001,APP ID 或 SECRET 錯誤,Invalid Basic Auth credentials,auth,error,檢查 APP ID 與 SECRET 是否正確 base64 編碼
52
+ pchomepay,10003,Token 已過期,Token expired,auth,error,重新呼叫 POST /v1/token 取得新 token
53
+ pchomepay,10004,Token 不存在,Token not found,auth,error,header 必須帶 pcpay-token
54
+ pchomepay,10005,IP 不在白名單,IP not whitelisted,auth,error,將呼叫端 IP 加入後台白名單
55
+ pchomepay,20001,訂單已存在,Duplicate order_id,validation,error,使用唯一 order_id
56
+ pchomepay,20002,訂單金額錯誤,Invalid amount,validation,error,amount 必須為正整數
57
+ pchomepay,30001,退款金額超過原訂單,Refund exceeds original,refund,error,退款金額 + 退款手續費需小於原訂單
58
+ pchomepay,30002,餘額不足,Insufficient balance,refund,error,商家代收帳戶餘額不足以扣除退款 + 手續費
59
+ pchomepay,40001,卡號驗證失敗,Card validation failed,payment,error,信用卡資料錯誤;於 sandbox 改用測試卡號
60
+ pchomepay,90001,超商取貨建立失敗,CVS COD creation failed,logistics,error,參見 taiwan-logistics 文件確認物流欄位
61
+ ezpay,KEY10001,商店代號錯誤,Invalid MerchantID,auth,error,確認 MerchantID 與後台一致
62
+ ezpay,KEY10002,簽章驗證失敗,TradeSha mismatch,auth,error,SHA256 計算需含 HashKey/HashIV 且大寫
63
+ ezpay,KEY10003,加密資料解密失敗,TradeInfo decrypt failed,auth,error,確認 AES-256-CBC + Hex + PKCS7 與 32-char HashKey 16-char HashIV
64
+ ezpay,MEM10001,商家未啟用該付款方式,Method not enabled,validation,error,於 ezPay 後台啟用該付款方式
65
+ ezpay,MPG10001,訂單編號重複,Duplicate MerchantOrderNo,validation,error,使用唯一訂單編號
66
+ ezpay,VACC10001,虛擬帳號逾期,VACC expired,validation,error,檢查 ExpireDate 設定
67
+ paynow,M001,商家代號錯誤,Invalid Merchant,auth,error,確認商家代號正確
68
+ paynow,A001,加密驗證失敗,Encryption validation failed,auth,error,傳統版檢查 GP/GK 動態金鑰;現代版檢查 JWT Bearer
69
+ paynow,B001,訂單金額錯誤,Invalid Amount,validation,error,確認 amount 為正整數且小於 1,000,000,000,000
70
+ paynow,C001,訂單編號重複,Duplicate paymentNo,validation,error,使用唯一 paymentNo (現代版可省略由系統產生)
71
+ paynow,P001,信用卡授權失敗,Card authorization failed,payment,error,改用其他卡或聯繫銀行
72
+ paynow,Q001,Token 過期,JWT expired,auth,error,重新申請 JWT Bearer Token
73
+ paynow,R001,退款超過原訂單,Refund exceeds original,refund,error,確認可退金額
74
+ paynow,T001,信用卡 token 不存在,Card token not found,payment,error,確認 customer 與 card token 仍有效
75
+ shopline,400,參數錯誤,Bad Request,validation,error,檢查 request body 與必填欄位
76
+ shopline,401,認證失敗,Unauthorized,auth,error,檢查 merchantId / apiKey HTTP header
77
+ shopline,403,沒有權限,Forbidden,auth,error,確認 API 權限與 IP 白名單
78
+ shopline,404,資源不存在,Not Found,resource,error,確認 sessionId / paymentId 正確
79
+ shopline,409,重複請求,Conflict,validation,error,使用唯一 referenceNumber
80
+ shopline,422,驗證失敗,Unprocessable Entity,validation,error,檢查欄位格式與業務規則
81
+ shopline,500,伺服器錯誤,Internal Server Error,server,error,稍後重試;持續出現聯繫 SLP support
82
+ linepay,1101,請求超時,Request Timeout,network,error,重試;通常為網路問題
83
+ linepay,1102,認證失敗,Authentication Failed,auth,error,檢查 ChannelId/ChannelSecret 與 HMAC 簽章
84
+ linepay,1104,商戶尚未上線,Merchant not activated,auth,error,於 LINE Pay Merchant Center 啟用商戶
85
+ linepay,1106,Header 錯誤,Header Error,validation,error,檢查 X-LINE-Authorization 與 Nonce
86
+ linepay,1133,認證資訊過期,Authentication Expired,auth,error,Nonce 不可重複;重新產生
87
+ linepay,1141,無效金額,Invalid Amount,validation,error,amount 必須為正整數
88
+ linepay,1142,無效幣別,Invalid Currency,validation,error,Currency 必須為 TWD/USD 等支援值
89
+ linepay,1170,訂單不存在,Order Not Found,resource,error,確認 transactionId
90
+ linepay,1172,訂單已存在,Duplicate Order,validation,error,使用唯一 orderId
91
+ linepay,1183,無效 Confirm,Invalid Confirm,validation,error,Confirm payload amount/currency 須與 Request 完全相同
92
+ linepay,1198,內部錯誤,Internal Error,server,error,聯繫 LINE Pay 技術支援
93
+ tappay,1,付款失敗,Payment Failure,payment,error,檢查 prime 與卡片是否有效
94
+ tappay,2,參數錯誤,Invalid Parameters,validation,error,檢查 partner_key/merchant_id 與 amount 等必填
95
+ tappay,3,prime 錯誤,Invalid Prime,validation,error,Prime 已使用或過期 (60秒);重新取得
96
+ tappay,4,卡片資訊錯誤,Invalid Card,validation,error,卡號/到期/CVC 不正確
97
+ tappay,5,卡片風控,Card Risk,risk,error,銀行風控拒絕;聯繫卡片發行銀行
98
+ tappay,6,系統錯誤,System Error,server,error,聯繫 TapPay 技術支援
99
+ tappay,7,卡片過期,Card Expired,validation,error,使用未過期卡片
100
+ tappay,10003,Partner Key 錯誤,Invalid Partner Key,auth,error,確認 Partner Key 與環境一致 (sandbox/prod)
101
+ tappay,10005,Merchant ID 錯誤,Invalid Merchant ID,auth,error,確認 Merchant ID 設定
102
+ tappay,88001,卡片驗證失敗,Card Verification Failed,validation,error,3DS 驗證失敗;聯繫銀行