taiwan-payment-skill 1.5.2 → 1.5.4

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 (43) hide show
  1. package/assets/taiwan-payment/CLAUDE.md +40 -21
  2. package/assets/taiwan-payment/EXAMPLES.md +196 -418
  3. package/assets/taiwan-payment/README.md +2 -2
  4. package/assets/taiwan-payment/SKILL.md +113 -170
  5. package/assets/taiwan-payment/data/error-codes.csv +2730 -114
  6. package/assets/taiwan-payment/data/field-mappings.csv +10 -10
  7. package/assets/taiwan-payment/data/operations.csv +7 -7
  8. package/assets/taiwan-payment/data/payment-methods.csv +25 -25
  9. package/assets/taiwan-payment/data/providers.csv +1 -1
  10. package/assets/taiwan-payment/data/troubleshooting.csv +9 -4
  11. package/assets/taiwan-payment/examples/ecpay-payment-example.py +32 -7
  12. package/assets/taiwan-payment/examples/ezpay-payment-example.py +290 -614
  13. package/assets/taiwan-payment/examples/jkopay-payment-example.py +13 -15
  14. package/assets/taiwan-payment/examples/linepay-payment-example.py +14 -9
  15. package/assets/taiwan-payment/examples/newebpay-payment-example.py +106 -22
  16. package/assets/taiwan-payment/examples/paynow-payment-example.py +5 -5
  17. package/assets/taiwan-payment/examples/payuni-payment-example.py +185 -349
  18. package/assets/taiwan-payment/examples/pchomepay-payment-example.py +0 -1
  19. package/assets/taiwan-payment/examples/shopline-payment-example.py +25 -26
  20. package/assets/taiwan-payment/examples/smilepay-payment-example.py +5 -4
  21. package/assets/taiwan-payment/examples/sunpay-payment-example.py +52 -23
  22. package/assets/taiwan-payment/examples/tappay-payment-example.py +0 -1
  23. package/assets/taiwan-payment/references/ecpay-payment-api.md +0 -2
  24. package/assets/taiwan-payment/references/ezpay-payment-api.md +231 -561
  25. package/assets/taiwan-payment/references/gomypay-payment-api.md +1 -2
  26. package/assets/taiwan-payment/references/jkopay-payment-api.md +2 -9
  27. package/assets/taiwan-payment/references/linepay-payment-api.md +36 -46
  28. package/assets/taiwan-payment/references/newebpay-payment-api.md +60 -47
  29. package/assets/taiwan-payment/references/opay-payment-api.md +26 -18
  30. package/assets/taiwan-payment/references/paynow-payment-api.md +0 -3
  31. package/assets/taiwan-payment/references/payuni-payment-api.md +162 -342
  32. package/assets/taiwan-payment/references/pchomepay-payment-api.md +0 -3
  33. package/assets/taiwan-payment/references/shopline-payment-api.md +9 -8
  34. package/assets/taiwan-payment/references/smilepay-payment-api.md +28 -59
  35. package/assets/taiwan-payment/references/sunpay-payment-api.md +36 -3
  36. package/assets/taiwan-payment/references/tappay-payment-api.md +16 -18
  37. package/assets/taiwan-payment/references/twqr-ewallet-landscape.md +11 -13
  38. package/assets/taiwan-payment/scripts/core.py +1 -2
  39. package/assets/taiwan-payment/scripts/recommend.py +1 -2
  40. package/assets/taiwan-payment/scripts/test_payment.py +65 -50
  41. package/assets/templates/base/quick-reference.md +9 -9
  42. package/assets/templates/base/skill-content.md +113 -171
  43. package/package.json +1 -1
@@ -50,7 +50,7 @@ taiwan-payment/ # Source of Truth
50
50
  └── data/ # Data-driven architecture (7 CSVs)
51
51
  ├── providers.csv # 14 providers(含 doc_access 文件公開程度分級)
52
52
  ├── operations.csv # 8 API operations
53
- ├── error-codes.csv # 120 error codes + solutions(11 家)
53
+ ├── error-codes.csv # 1190 error codes(11 家,依各家官方文件重建)
54
54
  ├── field-mappings.csv # 19 欄位 × 14 家 provider 對照
55
55
  ├── payment-methods.csv # 40 payment methods
56
56
  ├── reasoning.csv # 30+ recommendation rules
@@ -151,13 +151,14 @@ Never push directly to `main`. Always:
151
151
  ### Common Pitfalls
152
152
 
153
153
  1. **CheckMacValue calculation errors**:
154
- - Must sort parameters alphabetically
155
- - Must use lowercase URL encoding
154
+ - Sort parameters alphabetically, case-insensitive
155
+ - URL encode 後轉小寫,並把 `( ) ! * - _ .` 還原(.NET 規則;直接用 quote_plus 遇到括號就會錯)
156
156
  - Must exclude CheckMacValue itself from calculation
157
+ - 物流 API 用 MD5,金流 AIO 用 SHA256
157
158
 
158
159
  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
160
+ - NewebPay: Key=32 bytes, IV=16 bytes;解密須容許 1–32 bytes 的 padding,且 RespondType=JSON 時明文是 JSON
161
+ - PAYUNi: EncryptInfo = hex(base64(密文) + ":::" + base64(tag));HashInfo 為 HashKey + EncryptInfo + HashIV
161
162
 
162
163
  3. **Payment notification handling**:
163
164
  - Always verify CheckMacValue before processing
@@ -226,25 +227,45 @@ To add new data, edit CSV files directly. No code changes needed.
226
227
 
227
228
  ## Encryption Methods
228
229
 
229
- ### ECPay - SHA256
230
+ > 以下三段皆與業者官方實作逐位元組比對過(`tests/vectors/`,CI 執行 `scripts/verify-examples.py`)。
231
+ > 修改前請先跑該腳本;不要憑印象改演算法。
230
232
 
233
+ ### ECPay - SHA256 CheckMacValue(物流用 MD5)
234
+
235
+ <!-- verify: ecpay-cmv-sha256 -->
231
236
  ```python
237
+ def ecpay_url_encode(text):
238
+ # PHP urlencode → 小寫 → .NET 不編碼的 - _ . ! * ( ) 還原
239
+ encoded = urllib.parse.quote_plus(text, safe='').replace('~', '%7E').lower()
240
+ for src, dst in (('%2d', '-'), ('%5f', '_'), ('%2e', '.'), ('%21', '!'),
241
+ ('%2a', '*'), ('%28', '('), ('%29', ')')):
242
+ encoded = encoded.replace(src, dst)
243
+ return encoded
244
+
232
245
  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()
246
+ items = sorted(((k, v) for k, v in params.items() if k != 'CheckMacValue'),
247
+ key=lambda kv: kv[0].lower()) # 不分大小寫排序(SDK 用 strcasecmp)
248
+ raw = f"HashKey={hash_key}&{'&'.join(f'{k}={v}' for k, v in items)}&HashIV={hash_iv}"
249
+ return hashlib.sha256(ecpay_url_encode(raw).encode('utf-8')).hexdigest().upper()
238
250
  ```
239
251
 
240
252
  ### NewebPay - AES-256-CBC + SHA256
241
253
 
254
+ <!-- verify: newebpay -->
242
255
  ```python
243
256
  def generate_trade_info(params, hash_key, hash_iv):
244
- query_string = urllib.parse.urlencode(params)
245
257
  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()
258
+ return cipher.encrypt(pad(urllib.parse.urlencode(params).encode(), 16)).hex()
259
+
260
+ def decrypt_trade_info(trade_info, hash_key, hash_iv):
261
+ data = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode()).decrypt(bytes.fromhex(trade_info))
262
+ # 官方外掛以 32 bytes 區塊補齊,padding 可能是 1–32;unpad(data, 16) 會失敗
263
+ n = data[-1]
264
+ if not 1 <= n <= 32 or data[-n:] != bytes([n]) * n:
265
+ raise ValueError('padding 錯誤(金鑰或 IV 不正確)')
266
+ text = data[:-n].decode()
267
+ # RespondType=JSON 時明文是 JSON,不是 query string
268
+ return json.loads(text) if text.startswith('{') else dict(urllib.parse.parse_qsl(text, keep_blank_values=True))
248
269
 
249
270
  def generate_trade_sha(trade_info, hash_key, hash_iv):
250
271
  raw = f'HashKey={hash_key}&{trade_info}&HashIV={hash_iv}'
@@ -253,15 +274,16 @@ def generate_trade_sha(trade_info, hash_key, hash_iv):
253
274
 
254
275
  ### PAYUNi - AES-256-GCM + SHA256
255
276
 
277
+ <!-- verify: payuni -->
256
278
  ```python
257
279
  def generate_encrypt_info(params, hash_key, hash_iv):
258
- query_string = urllib.parse.urlencode(params)
259
280
  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!
281
+ encrypted, tag = cipher.encrypt_and_digest(urllib.parse.urlencode(params).encode())
282
+ # hex( base64(密文) + ":::" + base64(tag) ) —— 最外層的 hex 不可省略
283
+ return (base64.b64encode(encrypted) + b':::' + base64.b64encode(tag)).hex()
262
284
 
263
285
  def generate_hash_info(encrypt_info, hash_key, hash_iv):
264
- raw = encrypt_info + hash_key + hash_iv
286
+ raw = hash_key + encrypt_info + hash_iv # HashKey 在前
265
287
  return hashlib.sha256(raw.encode()).hexdigest().upper()
266
288
  ```
267
289
 
@@ -309,6 +331,3 @@ Before publishing to npm:
309
331
  - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego)
310
332
  - **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi)
311
333
 
312
- ---
313
-
314
- **Last Updated**: 2026-01-29