taiwan-payment-skill 1.5.1 → 1.5.3
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.
- package/assets/taiwan-payment/CLAUDE.md +40 -18
- package/assets/taiwan-payment/EXAMPLES.md +196 -414
- package/assets/taiwan-payment/README.md +2 -2
- package/assets/taiwan-payment/SKILL.md +113 -167
- package/assets/taiwan-payment/data/error-codes.csv +1106 -114
- package/assets/taiwan-payment/data/field-mappings.csv +10 -10
- package/assets/taiwan-payment/data/operations.csv +7 -7
- package/assets/taiwan-payment/data/payment-methods.csv +25 -25
- package/assets/taiwan-payment/data/providers.csv +1 -1
- package/assets/taiwan-payment/data/troubleshooting.csv +9 -4
- package/assets/taiwan-payment/examples/ecpay-payment-example.py +32 -6
- package/assets/taiwan-payment/examples/ezpay-payment-example.py +291 -613
- package/assets/taiwan-payment/examples/linepay-payment-example.py +12 -4
- package/assets/taiwan-payment/examples/newebpay-payment-example.py +106 -21
- package/assets/taiwan-payment/examples/paynow-payment-example.py +2 -1
- package/assets/taiwan-payment/examples/payuni-payment-example.py +186 -342
- package/assets/taiwan-payment/examples/shopline-payment-example.py +25 -25
- package/assets/taiwan-payment/examples/smilepay-payment-example.py +5 -3
- package/assets/taiwan-payment/examples/sunpay-payment-example.py +39 -8
- package/assets/taiwan-payment/references/ezpay-payment-api.md +235 -561
- package/assets/taiwan-payment/references/linepay-payment-api.md +37 -43
- package/assets/taiwan-payment/references/newebpay-payment-api.md +60 -47
- package/assets/taiwan-payment/references/opay-payment-api.md +25 -17
- package/assets/taiwan-payment/references/payuni-payment-api.md +162 -330
- package/assets/taiwan-payment/references/shopline-payment-api.md +9 -5
- package/assets/taiwan-payment/references/smilepay-payment-api.md +30 -56
- package/assets/taiwan-payment/references/sunpay-payment-api.md +35 -1
- package/assets/taiwan-payment/references/tappay-payment-api.md +17 -15
- package/assets/taiwan-payment/references/twqr-ewallet-landscape.md +5 -3
- package/assets/taiwan-payment/scripts/test_payment.py +65 -50
- package/assets/templates/base/quick-reference.md +9 -9
- package/assets/templates/base/skill-content.md +113 -168
- 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 #
|
|
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
|
-
-
|
|
155
|
-
-
|
|
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:
|
|
160
|
-
- PAYUNi:
|
|
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
|
-
|
|
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
|
-
|
|
234
|
-
|
|
235
|
-
raw = f
|
|
236
|
-
|
|
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
|
-
|
|
247
|
-
|
|
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(
|
|
261
|
-
|
|
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 =
|
|
286
|
+
raw = hash_key + encrypt_info + hash_iv # HashKey 在前
|
|
265
287
|
return hashlib.sha256(raw.encode()).hexdigest().upper()
|
|
266
288
|
```
|
|
267
289
|
|