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