taiwan-payment-skill 1.3.3 → 1.4.0

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 (60) hide show
  1. package/README.md +130 -130
  2. package/assets/taiwan-payment/CLAUDE.md +314 -304
  3. package/assets/taiwan-payment/EXAMPLES.md +1542 -1542
  4. package/assets/taiwan-payment/README.md +130 -130
  5. package/assets/taiwan-payment/SKILL.md +933 -933
  6. package/assets/taiwan-payment/data/error-codes.csv +189 -102
  7. package/assets/taiwan-payment/data/field-mappings.csv +18 -15
  8. package/assets/taiwan-payment/data/operations.csv +23 -23
  9. package/assets/taiwan-payment/data/payment-methods.csv +42 -39
  10. package/assets/taiwan-payment/data/providers.csv +15 -11
  11. package/assets/taiwan-payment/data/reasoning.csv +44 -32
  12. package/assets/taiwan-payment/data/troubleshooting.csv +37 -22
  13. package/assets/taiwan-payment/examples/ecpay-payment-example.py +390 -390
  14. package/assets/taiwan-payment/examples/ezpay-payment-example.py +690 -690
  15. package/assets/taiwan-payment/examples/linepay-payment-example.py +305 -305
  16. package/assets/taiwan-payment/examples/newebpay-payment-example.py +451 -451
  17. package/assets/taiwan-payment/examples/paynow-payment-example.py +767 -767
  18. package/assets/taiwan-payment/examples/payuni-payment-example.py +457 -457
  19. package/assets/taiwan-payment/examples/pchomepay-payment-example.py +556 -556
  20. package/assets/taiwan-payment/examples/shopline-payment-example.py +291 -291
  21. package/assets/taiwan-payment/examples/smilepay-payment-example.py +673 -673
  22. package/assets/taiwan-payment/examples/tappay-payment-example.py +337 -337
  23. package/assets/taiwan-payment/references/ecpay-payment-api.md +933 -933
  24. package/assets/taiwan-payment/references/ezpay-payment-api.md +660 -660
  25. package/assets/taiwan-payment/references/gomypay-payment-api.md +62 -0
  26. package/assets/taiwan-payment/references/jkopay-payment-api.md +600 -0
  27. package/assets/taiwan-payment/references/linepay-payment-api.md +940 -940
  28. package/assets/taiwan-payment/references/newebpay-payment-api.md +677 -677
  29. package/assets/taiwan-payment/references/opay-payment-api.md +265 -0
  30. package/assets/taiwan-payment/references/paynow-payment-api.md +1654 -1654
  31. package/assets/taiwan-payment/references/payuni-payment-api.md +1018 -1018
  32. package/assets/taiwan-payment/references/pchomepay-payment-api.md +1431 -1431
  33. package/assets/taiwan-payment/references/shopline-payment-api.md +1523 -1523
  34. package/assets/taiwan-payment/references/smilepay-payment-api.md +919 -919
  35. package/assets/taiwan-payment/references/sunpay-payment-api.md +369 -0
  36. package/assets/taiwan-payment/references/tappay-payment-api.md +1245 -1245
  37. package/assets/taiwan-payment/references/twqr-ewallet-landscape.md +160 -0
  38. package/assets/taiwan-payment/scripts/core.py +346 -288
  39. package/assets/taiwan-payment/scripts/recommend.py +289 -277
  40. package/assets/taiwan-payment/scripts/search.py +185 -185
  41. package/assets/taiwan-payment/scripts/test_payment.py +358 -358
  42. package/assets/taiwan-payment/scripts/test_recommend.py +114 -0
  43. package/assets/templates/base/quick-reference.md +71 -71
  44. package/assets/templates/base/skill-content.md +928 -928
  45. package/assets/templates/platforms/agent.json +26 -26
  46. package/assets/templates/platforms/antigravity.json +25 -25
  47. package/assets/templates/platforms/claude.json +26 -26
  48. package/assets/templates/platforms/codebuddy.json +25 -25
  49. package/assets/templates/platforms/codex.json +26 -26
  50. package/assets/templates/platforms/continue.json +25 -25
  51. package/assets/templates/platforms/copilot.json +25 -25
  52. package/assets/templates/platforms/cursor.json +26 -26
  53. package/assets/templates/platforms/gemini.json +25 -25
  54. package/assets/templates/platforms/kiro.json +25 -25
  55. package/assets/templates/platforms/opencode.json +25 -25
  56. package/assets/templates/platforms/qoder.json +25 -25
  57. package/assets/templates/platforms/roocode.json +25 -25
  58. package/assets/templates/platforms/trae.json +25 -25
  59. package/assets/templates/platforms/windsurf.json +25 -25
  60. package/package.json +67 -67
@@ -1,304 +1,314 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
- ## Project Overview
6
-
7
- Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for major payment platforms (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
-
9
- ## Available Scripts
10
-
11
- ```bash
12
- # Search API documentation
13
- python3 taiwan-payment/scripts/search.py "<query>" [--domain <domain>]
14
-
15
- # Recommend payment provider
16
- python3 taiwan-payment/scripts/recommend.py "<requirements>"
17
-
18
- # Test API connectivity
19
- python3 taiwan-payment/scripts/test_payment.py [--platform <platform>]
20
- ```
21
-
22
- **Supported Platforms:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `ezpay`, `paynow`
23
-
24
- **Search Domains:** `provider`, `operation`, `error`, `field`, `payment_method`, `troubleshoot`, `reasoning`
25
-
26
- ## Architecture
27
-
28
- ```
29
- taiwan-payment/ # Source of Truth
30
- ├── SKILL.md # Main skill documentation
31
- ├── EXAMPLES.md # Code examples and patterns
32
- ├── references/ # API documentation
33
- │ ├── ecpay-payment-api.md
34
- │ ├── newebpay-payment-api.md
35
- │ ├── payuni-payment-api.md
36
- │ ├── smilepay-payment-api.md
37
- │ ├── pchomepay-payment-api.md
38
- │ ├── ezpay-payment-api.md
39
- │ ├── paynow-payment-api.md
40
- │ ├── shopline-payment-api.md
41
- │ ├── linepay-payment-api.md
42
- │ └── tappay-payment-api.md
43
- ├── scripts/ # Utility scripts
44
- │ ├── core.py # BM25 search engine
45
- │ ├── recommend.py # Recommendation system
46
- │ ├── search.py # Search CLI (150+ lines)
47
- │ └── test_payment.py # Connection testing
48
- └── data/ # Data-driven architecture (7 CSVs)
49
- ├── providers.csv # 3 providers with details
50
- ├── operations.csv # 8 API operations
51
- ├── error-codes.csv # 20+ error codes + solutions
52
- ├── field-mappings.csv # 15 field mappings
53
- ├── payment-methods.csv # 24 payment methods
54
- ├── reasoning.csv # 30+ recommendation rules
55
- └── troubleshooting.csv # 16 troubleshooting cases
56
-
57
- cli/ # CLI installer (taiwan-payment-skill on npm)
58
- ├── src/
59
- │ ├── commands/init.ts # Install command with template generation
60
- │ ├── utils/template.ts # Template rendering engine
61
- │ ├── utils/detect.ts # AI type detection
62
- │ └── utils/logger.ts # Logging utilities
63
- └── assets/ # Bundled assets
64
- ├── taiwan-payment/ # Copy of taiwan-payment/
65
- └── templates/
66
- ├── base/ # Base templates (skill-content.md, quick-reference.md)
67
- └── platforms/ # Platform configs (14 platforms)
68
-
69
- .claude/skills/taiwan-payment/ # Claude Code skill (generated by CLI)
70
- ```
71
-
72
- ## Sync Rules
73
-
74
- **Source of Truth:** `taiwan-payment/`
75
-
76
- When modifying files:
77
-
78
- 1. **Skill Content** - Edit in `taiwan-payment/`:
79
- - `SKILL.md` - Main documentation
80
- - `EXAMPLES.md` - Code examples
81
- - `references/*.md` - API documentation
82
- - `scripts/*.py` - Utility scripts
83
- - `data/*.csv` - Data files
84
-
85
- 2. **Templates** - Edit in `cli/assets/templates/`:
86
- - `base/skill-content.md` - Common skill content
87
- - `base/quick-reference.md` - Quick reference (Claude only)
88
- - `platforms/*.json` - Platform-specific configs (14 platforms)
89
-
90
- 3. **CLI Assets** - Run sync before publishing:
91
- ```bash
92
- cp -r taiwan-payment/* cli/assets/taiwan-payment/
93
- ```
94
-
95
- 4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-payment init`.
96
-
97
- ## Supported AI Platforms
98
-
99
- | Platform | Folder | Install Type |
100
- |-------------|-------------|--------------|
101
- | Claude Code | `.claude` | full |
102
- | Cursor | `.cursor` | full |
103
- | Windsurf | `.windsurf` | full |
104
- | Antigravity | `.agent` | full |
105
- | Copilot | `.github` | full |
106
- | Kiro | `.kiro` | full |
107
- | Codex | `.codex` | full |
108
- | Qoder | `.qoder` | full |
109
- | Roo Code | `.roo` | full |
110
- | Gemini | `.gemini` | full |
111
- | Trae | `.trae` | full |
112
- | OpenCode | `.opencode` | full |
113
- | Continue | `.continue` | full |
114
- | CodeBuddy | `.codebuddy`| full |
115
-
116
- ## Prerequisites
117
-
118
- - Node.js 18+ (for CLI)
119
- - Python 3.x (for scripts, no external dependencies)
120
-
121
- ## Git Workflow
122
-
123
- Never push directly to `main`. Always:
124
-
125
- 1. Create a new branch: `git checkout -b feat/...` or `fix/...`
126
- 2. Commit changes
127
- 3. Push branch: `git push -u origin <branch>`
128
- 4. Create PR: `gh pr create`
129
-
130
- ## Development Guidelines
131
-
132
- ### When Working with Payment Integration
133
-
134
- 1. **Always verify CheckMacValue/CheckSum** - This is the most critical security measure
135
- 2. **Use test accounts** - Never use production credentials in examples
136
- 3. **Handle errors gracefully** - Payment failures are common, always provide fallback
137
- 4. **HTTPS only** - All callback URLs must use HTTPS
138
- 5. **Amount validation** - Always validate amounts are positive integers
139
- 6. **Idempotency** - Ensure order IDs are unique to prevent duplicate payments
140
-
141
- ### Common Pitfalls
142
-
143
- 1. **CheckMacValue calculation errors**:
144
- - Must sort parameters alphabetically
145
- - Must use lowercase URL encoding
146
- - Must exclude CheckMacValue itself from calculation
147
-
148
- 2. **AES encryption errors**:
149
- - NewebPay: Ensure Key=32 bytes, IV=16 bytes, use PKCS7 padding
150
- - PAYUNi: Must append 16-byte auth tag after encryption
151
-
152
- 3. **Payment notification handling**:
153
- - Always verify CheckMacValue before processing
154
- - Return "1|OK" for ECPay, handle appropriately for others
155
- - Use database transactions to prevent duplicate processing
156
-
157
- ### Code Review Checklist
158
-
159
- - [ ] Sensitive data (HashKey/HashIV) not exposed in frontend
160
- - [ ] CheckMacValue/CheckSum properly calculated and verified
161
- - [ ] HTTPS used for all callback URLs
162
- - [ ] Proper error handling for payment failures
163
- - [ ] Unique order IDs generated
164
- - [ ] Test accounts used in examples
165
- - [ ] Comments explain complex encryption logic
166
- - [ ] CSV data validated and consistent
167
-
168
- ## Smart Tools Usage
169
-
170
- ### BM25 Search
171
-
172
- Use when user asks about:
173
- - "What's error code 10100058?"
174
- - "How to map MerchantID field?"
175
- - "Which payment methods does ECPay support?"
176
-
177
- ```bash
178
- python3 scripts/search.py "<query>" [--domain <domain>] [--format json]
179
- ```
180
-
181
- ### Recommendation System
182
-
183
- Use when user asks:
184
- - "Which payment provider should I use?"
185
- - "Best for high-volume e-commerce?"
186
- - "Need LINE Pay integration"
187
-
188
- ```bash
189
- python3 scripts/recommend.py "<requirements>" [--format ascii|json|simple]
190
- ```
191
-
192
- ### Connection Testing
193
-
194
- Use when user wants to:
195
- - Test API connectivity
196
- - Verify encryption implementation
197
- - Check test credentials
198
-
199
- ```bash
200
- python3 scripts/test_payment.py [--platform ecpay|newebpay|payuni]
201
- ```
202
-
203
- ## Data-Driven Architecture
204
-
205
- All core logic is in CSV files:
206
-
207
- - **providers.csv** - Provider details (encryption, API endpoints, test accounts)
208
- - **operations.csv** - API operations (create, query, refund, etc.)
209
- - **error-codes.csv** - Error code lookup table
210
- - **field-mappings.csv** - Field name mappings across providers
211
- - **payment-methods.csv** - Payment method details
212
- - **reasoning.csv** - Recommendation rules (30+ scenarios)
213
- - **troubleshooting.csv** - Common issues and solutions
214
-
215
- To add new data, edit CSV files directly. No code changes needed.
216
-
217
- ## Encryption Methods
218
-
219
- ### ECPay - SHA256
220
-
221
- ```python
222
- def generate_check_mac_value(params, hash_key, hash_iv):
223
- sorted_params = sorted(params.items())
224
- param_str = '&'.join(f'{k}={v}' for k, v in sorted_params)
225
- raw = f'HashKey={hash_key}&{param_str}&HashIV={hash_iv}'
226
- encoded = urllib.parse.quote_plus(raw).lower()
227
- return hashlib.sha256(encoded.encode('utf-8')).hexdigest().upper()
228
- ```
229
-
230
- ### NewebPay - AES-256-CBC + SHA256
231
-
232
- ```python
233
- def generate_trade_info(params, hash_key, hash_iv):
234
- query_string = urllib.parse.urlencode(params)
235
- cipher = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode())
236
- padded = pad(query_string.encode(), AES.block_size)
237
- return cipher.encrypt(padded).hex()
238
-
239
- def generate_trade_sha(trade_info, hash_key, hash_iv):
240
- raw = f'HashKey={hash_key}&{trade_info}&HashIV={hash_iv}'
241
- return hashlib.sha256(raw.encode()).hexdigest().upper()
242
- ```
243
-
244
- ### PAYUNi - AES-256-GCM + SHA256
245
-
246
- ```python
247
- def generate_encrypt_info(params, hash_key, hash_iv):
248
- query_string = urllib.parse.urlencode(params)
249
- cipher = AES.new(hash_key.encode(), AES.MODE_GCM, nonce=hash_iv.encode())
250
- encrypted, tag = cipher.encrypt_and_digest(query_string.encode())
251
- return (encrypted + tag).hex() # Must append tag!
252
-
253
- def generate_hash_info(encrypt_info, hash_key, hash_iv):
254
- raw = encrypt_info + hash_key + hash_iv
255
- return hashlib.sha256(raw.encode()).hexdigest().upper()
256
- ```
257
-
258
- ## Test Accounts
259
-
260
- ### ECPay
261
- ```
262
- 商店代號: 3002607
263
- HashKey: pwFHCqoQZGmho4w6
264
- HashIV: EkRm7iFT261dpevs
265
- 測試網址: https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
266
- 測試卡號: 4311-9522-2222-2222
267
- ```
268
-
269
- ### NewebPay
270
- ```
271
- 商店代號: 請至後台申請
272
- HashKey: 請至後台申請
273
- HashIV: 請至後台申請
274
- 測試網址: https://ccore.newebpay.com/MPG/mpg_gateway
275
- 測試卡號: 4000-2211-1111-1111
276
- ```
277
-
278
- ### PAYUNi
279
- ```
280
- 商店代號: 請至後台申請
281
- HashKey: 請至後台申請
282
- HashIV: 請至後台申請
283
- 測試網址: https://sandbox-api.payuni.com.tw/api/upp
284
- 測試卡號: 4000-2211-1111-1111
285
- ```
286
-
287
- ## Publishing Workflow
288
-
289
- Before publishing to npm:
290
-
291
- 1. Update version in `cli/package.json`
292
- 2. Sync assets: `cp -r taiwan-payment/* cli/assets/taiwan-payment/`
293
- 3. Build CLI: `cd cli && npm run build`
294
- 4. Test locally: `npm test`
295
- 5. Publish: `npm publish`
296
-
297
- ## Related Projects
298
-
299
- - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego)
300
- - **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi)
301
-
302
- ---
303
-
304
- **Last Updated**: 2026-01-29
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for major payment platforms (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
+
9
+ ## Available Scripts
10
+
11
+ ```bash
12
+ # Search API documentation
13
+ python3 taiwan-payment/scripts/search.py "<query>" [--domain <domain>]
14
+
15
+ # Recommend payment provider
16
+ python3 taiwan-payment/scripts/recommend.py "<requirements>"
17
+
18
+ # Test API connectivity
19
+ python3 taiwan-payment/scripts/test_payment.py [--platform <platform>]
20
+ ```
21
+
22
+ **Supported Platforms:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `ezpay`, `paynow`, `shopline`, `linepay`, `tappay`, `opay`, `jkopay`, `sunpay`, `gomypay`
23
+
24
+ **電子支付錢包生態(街口/全支付/全盈+PAY/悠遊付/一卡通/icash Pay/橘子支/TWQR/零售自有 pay):** 見 `references/twqr-ewallet-landscape.md`——多數不直接串,走聚合商或 TWQR。
25
+
26
+ **Search Domains:** `provider`, `operation`, `error`, `field`, `payment_method`, `troubleshoot`, `reasoning`
27
+
28
+ ## Architecture
29
+
30
+ ```
31
+ taiwan-payment/ # Source of Truth
32
+ ├── SKILL.md # Main skill documentation
33
+ ├── EXAMPLES.md # Code examples and patterns
34
+ ├── references/ # API documentation
35
+ │ ├── ecpay-payment-api.md
36
+ │ ├── newebpay-payment-api.md
37
+ │ ├── payuni-payment-api.md
38
+ │ ├── smilepay-payment-api.md
39
+ │ ├── pchomepay-payment-api.md
40
+ │ ├── ezpay-payment-api.md
41
+ │ ├── paynow-payment-api.md
42
+ │ ├── shopline-payment-api.md
43
+ │ ├── linepay-payment-api.md
44
+ │ └── tappay-payment-api.md
45
+ ├── scripts/ # Utility scripts
46
+ │ ├── core.py # BM25 search engine
47
+ │ ├── recommend.py # Recommendation system
48
+ │ ├── search.py # Search CLI (150+ lines)
49
+ │ └── test_payment.py # Connection testing
50
+ └── data/ # Data-driven architecture (7 CSVs)
51
+ ├── providers.csv # 14 providers(含 doc_access 文件公開程度分級)
52
+ ├── operations.csv # 8 API operations
53
+ ├── error-codes.csv # 120 error codes + solutions(11 家)
54
+ ├── field-mappings.csv # 15 field mappings
55
+ ├── payment-methods.csv # 40 payment methods
56
+ ├── reasoning.csv # 30+ recommendation rules
57
+ └── troubleshooting.csv # 16 troubleshooting cases
58
+
59
+ cli/ # CLI installer (taiwan-payment-skill on npm)
60
+ ├── src/
61
+ │ ├── commands/init.ts # Install command with template generation
62
+ │ ├── utils/template.ts # Template rendering engine
63
+ │ ├── utils/detect.ts # AI type detection
64
+ │ └── utils/logger.ts # Logging utilities
65
+ └── assets/ # Bundled assets
66
+ ├── taiwan-payment/ # Copy of taiwan-payment/
67
+ └── templates/
68
+ ├── base/ # Base templates (skill-content.md, quick-reference.md)
69
+ └── platforms/ # Platform configs (14 platforms)
70
+
71
+ .claude/skills/taiwan-payment/ # Claude Code skill (generated by CLI)
72
+ ```
73
+
74
+ ## Sync Rules
75
+
76
+ **Source of Truth:** `taiwan-payment/`
77
+
78
+ When modifying files:
79
+
80
+ 1. **Skill Content** - Edit in `taiwan-payment/`:
81
+ - `SKILL.md` - Main documentation
82
+ - `EXAMPLES.md` - Code examples
83
+ - `references/*.md` - API documentation
84
+ - `scripts/*.py` - Utility scripts
85
+ - `data/*.csv` - Data files
86
+
87
+ 2. **Templates** - Edit in `cli/assets/templates/`:
88
+ - `base/skill-content.md` - Common skill content
89
+ - `base/quick-reference.md` - Quick reference (Claude only)
90
+ - `platforms/*.json` - Platform-specific configs (14 platforms)
91
+
92
+ 3. **CLI Assets** - 自動同步,無需手動複製:
93
+ - `<cli>/scripts/build.js` 會在打包前呼叫 `scripts/sync-assets.mjs`,
94
+ 因此 `npm run build` 與 `npm publish`(透過 prepublishOnly)都會自動帶到最新內容
95
+ - 發布流程另以 `node scripts/sync-assets.mjs --check` 驗證,落差會擋下發布
96
+
97
+ ```bash
98
+ node scripts/sync-assets.mjs # 手動同步全部
99
+ node scripts/sync-assets.mjs --check # 只檢查,有落差 exit 1
100
+ ```
101
+
102
+ > assets 會隨 npm publish 一起發布(package.json 的 `files` 含 `assets`),
103
+ > 過去忘記同步會靜默發出過期的 skill 內容,因此改為自動化。
104
+
105
+ 4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-payment init`.
106
+
107
+ ## Supported AI Platforms
108
+
109
+ | Platform | Folder | Install Type |
110
+ |-------------|-------------|--------------|
111
+ | Claude Code | `.claude` | full |
112
+ | Cursor | `.cursor` | full |
113
+ | Windsurf | `.windsurf` | full |
114
+ | Antigravity | `.agent` | full |
115
+ | Copilot | `.github` | full |
116
+ | Kiro | `.kiro` | full |
117
+ | Codex | `.codex` | full |
118
+ | Qoder | `.qoder` | full |
119
+ | Roo Code | `.roo` | full |
120
+ | Gemini | `.gemini` | full |
121
+ | Trae | `.trae` | full |
122
+ | OpenCode | `.opencode` | full |
123
+ | Continue | `.continue` | full |
124
+ | CodeBuddy | `.codebuddy`| full |
125
+
126
+ ## Prerequisites
127
+
128
+ - Node.js 18+ (for CLI)
129
+ - Python 3.x (for scripts, no external dependencies)
130
+
131
+ ## Git Workflow
132
+
133
+ Never push directly to `main`. Always:
134
+
135
+ 1. Create a new branch: `git checkout -b feat/...` or `fix/...`
136
+ 2. Commit changes
137
+ 3. Push branch: `git push -u origin <branch>`
138
+ 4. Create PR: `gh pr create`
139
+
140
+ ## Development Guidelines
141
+
142
+ ### When Working with Payment Integration
143
+
144
+ 1. **Always verify CheckMacValue/CheckSum** - This is the most critical security measure
145
+ 2. **Use test accounts** - Never use production credentials in examples
146
+ 3. **Handle errors gracefully** - Payment failures are common, always provide fallback
147
+ 4. **HTTPS only** - All callback URLs must use HTTPS
148
+ 5. **Amount validation** - Always validate amounts are positive integers
149
+ 6. **Idempotency** - Ensure order IDs are unique to prevent duplicate payments
150
+
151
+ ### Common Pitfalls
152
+
153
+ 1. **CheckMacValue calculation errors**:
154
+ - Must sort parameters alphabetically
155
+ - Must use lowercase URL encoding
156
+ - Must exclude CheckMacValue itself from calculation
157
+
158
+ 2. **AES encryption errors**:
159
+ - NewebPay: Ensure Key=32 bytes, IV=16 bytes, use PKCS7 padding
160
+ - PAYUNi: Must append 16-byte auth tag after encryption
161
+
162
+ 3. **Payment notification handling**:
163
+ - Always verify CheckMacValue before processing
164
+ - Return "1|OK" for ECPay, handle appropriately for others
165
+ - Use database transactions to prevent duplicate processing
166
+
167
+ ### Code Review Checklist
168
+
169
+ - [ ] Sensitive data (HashKey/HashIV) not exposed in frontend
170
+ - [ ] CheckMacValue/CheckSum properly calculated and verified
171
+ - [ ] HTTPS used for all callback URLs
172
+ - [ ] Proper error handling for payment failures
173
+ - [ ] Unique order IDs generated
174
+ - [ ] Test accounts used in examples
175
+ - [ ] Comments explain complex encryption logic
176
+ - [ ] CSV data validated and consistent
177
+
178
+ ## Smart Tools Usage
179
+
180
+ ### BM25 Search
181
+
182
+ Use when user asks about:
183
+ - "What's error code 10100058?"
184
+ - "How to map MerchantID field?"
185
+ - "Which payment methods does ECPay support?"
186
+
187
+ ```bash
188
+ python3 scripts/search.py "<query>" [--domain <domain>] [--format json]
189
+ ```
190
+
191
+ ### Recommendation System
192
+
193
+ Use when user asks:
194
+ - "Which payment provider should I use?"
195
+ - "Best for high-volume e-commerce?"
196
+ - "Need LINE Pay integration"
197
+
198
+ ```bash
199
+ python3 scripts/recommend.py "<requirements>" [--format ascii|json|simple]
200
+ ```
201
+
202
+ ### Connection Testing
203
+
204
+ Use when user wants to:
205
+ - Test API connectivity
206
+ - Verify encryption implementation
207
+ - Check test credentials
208
+
209
+ ```bash
210
+ python3 scripts/test_payment.py [--platform ecpay|newebpay|payuni]
211
+ ```
212
+
213
+ ## Data-Driven Architecture
214
+
215
+ All core logic is in CSV files:
216
+
217
+ - **providers.csv** - Provider details (encryption, API endpoints, test accounts)
218
+ - **operations.csv** - API operations (create, query, refund, etc.)
219
+ - **error-codes.csv** - Error code lookup table
220
+ - **field-mappings.csv** - Field name mappings across providers
221
+ - **payment-methods.csv** - Payment method details
222
+ - **reasoning.csv** - Recommendation rules (30+ scenarios)
223
+ - **troubleshooting.csv** - Common issues and solutions
224
+
225
+ To add new data, edit CSV files directly. No code changes needed.
226
+
227
+ ## Encryption Methods
228
+
229
+ ### ECPay - SHA256
230
+
231
+ ```python
232
+ def generate_check_mac_value(params, hash_key, hash_iv):
233
+ sorted_params = sorted(params.items())
234
+ param_str = '&'.join(f'{k}={v}' for k, v in sorted_params)
235
+ raw = f'HashKey={hash_key}&{param_str}&HashIV={hash_iv}'
236
+ encoded = urllib.parse.quote_plus(raw).lower()
237
+ return hashlib.sha256(encoded.encode('utf-8')).hexdigest().upper()
238
+ ```
239
+
240
+ ### NewebPay - AES-256-CBC + SHA256
241
+
242
+ ```python
243
+ def generate_trade_info(params, hash_key, hash_iv):
244
+ query_string = urllib.parse.urlencode(params)
245
+ cipher = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode())
246
+ padded = pad(query_string.encode(), AES.block_size)
247
+ return cipher.encrypt(padded).hex()
248
+
249
+ def generate_trade_sha(trade_info, hash_key, hash_iv):
250
+ raw = f'HashKey={hash_key}&{trade_info}&HashIV={hash_iv}'
251
+ return hashlib.sha256(raw.encode()).hexdigest().upper()
252
+ ```
253
+
254
+ ### PAYUNi - AES-256-GCM + SHA256
255
+
256
+ ```python
257
+ def generate_encrypt_info(params, hash_key, hash_iv):
258
+ query_string = urllib.parse.urlencode(params)
259
+ cipher = AES.new(hash_key.encode(), AES.MODE_GCM, nonce=hash_iv.encode())
260
+ encrypted, tag = cipher.encrypt_and_digest(query_string.encode())
261
+ return (encrypted + tag).hex() # Must append tag!
262
+
263
+ def generate_hash_info(encrypt_info, hash_key, hash_iv):
264
+ raw = encrypt_info + hash_key + hash_iv
265
+ return hashlib.sha256(raw.encode()).hexdigest().upper()
266
+ ```
267
+
268
+ ## Test Accounts
269
+
270
+ ### ECPay
271
+ ```
272
+ 商店代號: 3002607
273
+ HashKey: pwFHCqoQZGmho4w6
274
+ HashIV: EkRm7iFT261dpevs
275
+ 測試網址: https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
276
+ 測試卡號: 4311-9522-2222-2222
277
+ ```
278
+
279
+ ### NewebPay
280
+ ```
281
+ 商店代號: 請至後台申請
282
+ HashKey: 請至後台申請
283
+ HashIV: 請至後台申請
284
+ 測試網址: https://ccore.newebpay.com/MPG/mpg_gateway
285
+ 測試卡號: 4000-2211-1111-1111
286
+ ```
287
+
288
+ ### PAYUNi
289
+ ```
290
+ 商店代號: 請至後台申請
291
+ HashKey: 請至後台申請
292
+ HashIV: 請至後台申請
293
+ 測試網址: https://sandbox-api.payuni.com.tw/api/upp
294
+ 測試卡號: 4000-2211-1111-1111
295
+ ```
296
+
297
+ ## Publishing Workflow
298
+
299
+ Before publishing to npm:
300
+
301
+ 1. Update version in `cli/package.json`
302
+ 2. Sync assets: 由 `npm run build` 自動處理(`scripts/sync-assets.mjs`)
303
+ 3. Build CLI: `cd cli && npm run build`
304
+ 4. Test locally: `npm test`
305
+ 5. Publish: `npm publish`
306
+
307
+ ## Related Projects
308
+
309
+ - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego)
310
+ - **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi)
311
+
312
+ ---
313
+
314
+ **Last Updated**: 2026-01-29