taiwan-payment-skill 1.0.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 (37) hide show
  1. package/README.md +197 -0
  2. package/assets/taiwan-payment/CLAUDE.md +297 -0
  3. package/assets/taiwan-payment/EXAMPLES.md +1425 -0
  4. package/assets/taiwan-payment/README.md +306 -0
  5. package/assets/taiwan-payment/SKILL.md +857 -0
  6. package/assets/taiwan-payment/data/error-codes.csv +20 -0
  7. package/assets/taiwan-payment/data/field-mappings.csv +15 -0
  8. package/assets/taiwan-payment/data/operations.csv +8 -0
  9. package/assets/taiwan-payment/data/payment-methods.csv +24 -0
  10. package/assets/taiwan-payment/data/providers.csv +4 -0
  11. package/assets/taiwan-payment/data/reasoning.csv +32 -0
  12. package/assets/taiwan-payment/data/troubleshooting.csv +18 -0
  13. package/assets/taiwan-payment/references/ecpay-payment-api.md +880 -0
  14. package/assets/taiwan-payment/references/newebpay-payment-api.md +677 -0
  15. package/assets/taiwan-payment/references/payuni-payment-api.md +997 -0
  16. package/assets/taiwan-payment/scripts/core.py +288 -0
  17. package/assets/taiwan-payment/scripts/recommend.py +269 -0
  18. package/assets/taiwan-payment/scripts/search.py +185 -0
  19. package/assets/taiwan-payment/scripts/test_payment.py +358 -0
  20. package/assets/templates/base/quick-reference.md +370 -0
  21. package/assets/templates/base/skill-content.md +851 -0
  22. package/assets/templates/platforms/antigravity.json +25 -0
  23. package/assets/templates/platforms/claude.json +26 -0
  24. package/assets/templates/platforms/codebuddy.json +25 -0
  25. package/assets/templates/platforms/codex.json +25 -0
  26. package/assets/templates/platforms/continue.json +25 -0
  27. package/assets/templates/platforms/copilot.json +25 -0
  28. package/assets/templates/platforms/cursor.json +25 -0
  29. package/assets/templates/platforms/gemini.json +25 -0
  30. package/assets/templates/platforms/kiro.json +25 -0
  31. package/assets/templates/platforms/opencode.json +25 -0
  32. package/assets/templates/platforms/qoder.json +25 -0
  33. package/assets/templates/platforms/roocode.json +25 -0
  34. package/assets/templates/platforms/trae.json +25 -0
  35. package/assets/templates/platforms/windsurf.json +25 -0
  36. package/dist/index.js +17095 -0
  37. package/package.json +58 -0
@@ -0,0 +1,677 @@
1
+ # NewebPay Payment API Reference
2
+
3
+ 藍新金流 (NewebPay) 金流 API 完整參考文件。
4
+
5
+ ---
6
+
7
+ ## 目錄
8
+
9
+ 1. [API 端點總覽](#api-端點總覽)
10
+ 2. [測試環境](#測試環境)
11
+ 3. [加解密機制](#加解密機制)
12
+ 4. [MPG 交易](#mpg-交易)
13
+ 5. [單筆交易查詢](#單筆交易查詢)
14
+ 6. [取消授權](#取消授權)
15
+ 7. [請退款/取消請退款](#請退款取消請退款)
16
+ 8. [電子錢包退款](#電子錢包退款)
17
+ 9. [付款結果通知](#付款結果通知)
18
+ 10. [錯誤碼對照表](#錯誤碼對照表)
19
+
20
+ ---
21
+
22
+ ## API 端點總覽
23
+
24
+ ### 基礎 API 路徑
25
+
26
+ | 環境 | 基礎路徑 |
27
+ |------|----------|
28
+ | **測試環境** | `https://ccore.newebpay.com` |
29
+ | **正式環境** | `https://core.newebpay.com` |
30
+
31
+ ### 端點列表
32
+
33
+ | 功能 | 端點路徑 | 說明 |
34
+ |------|----------|------|
35
+ | MPG 交易 | `/MPG/mpg_gateway` | 幕前支付頁面 |
36
+ | 單筆查詢 | `/API/QueryTradeInfo` | 查詢交易狀態 |
37
+ | 取消授權 | `/API/CreditCard/Cancel` | 取消信用卡授權 |
38
+ | 請退款 | `/API/CreditCard/Close` | 信用卡請款/退款 |
39
+ | 電子錢包退款 | `/API/EWallet/refund` | 錢包類退款 |
40
+
41
+ ---
42
+
43
+ ## 測試環境
44
+
45
+ ### 測試帳號
46
+
47
+ 測試帳號請至藍新金流後台申請:
48
+
49
+ ```
50
+ 後台網址: https://www.newebpay.com/
51
+ 路徑: 會員中心 > 商店管理 > 商店資料設定 > 串接設定
52
+ ```
53
+
54
+ 取得以下資訊:
55
+ - **商店代號 (MerchantID)**
56
+ - **Hash Key**
57
+ - **Hash IV**
58
+
59
+ ### 測試信用卡
60
+
61
+ | 卡號 | 說明 |
62
+ |------|------|
63
+ | `4000-2211-1111-1111` | 一般測試卡 |
64
+ | `4761-5311-1111-1114` | 美國運通測試卡 |
65
+
66
+ - **有效期限**: 任意未過期日期 (格式 MMYY)
67
+ - **CVV/CVC**: 任意 3 碼
68
+
69
+ ---
70
+
71
+ ## 加解密機制
72
+
73
+ 藍新金流採用 **AES-256-CBC** 加密與 **SHA256** 驗證。
74
+
75
+ ### 加密流程
76
+
77
+ 1. **準備參數** - 組合所有請求參數
78
+ 2. **URL Encode** - 將參數組成 Query String
79
+ 3. **AES-256-CBC 加密** - 使用 Hash Key 和 Hash IV
80
+ 4. **轉十六進制** - 將加密結果轉 Hex
81
+ 5. **SHA256 雜湊** - 產生 TradeSha 驗證碼
82
+
83
+ ### PHP 加密範例
84
+
85
+ ```php
86
+ <?php
87
+
88
+ class NewebPayEncryption
89
+ {
90
+ private string $hashKey;
91
+ private string $hashIV;
92
+
93
+ public function __construct(string $hashKey, string $hashIV)
94
+ {
95
+ $this->hashKey = $hashKey;
96
+ $this->hashIV = $hashIV;
97
+ }
98
+
99
+ /**
100
+ * AES-256-CBC 加密
101
+ */
102
+ public function encrypt(array $params): string
103
+ {
104
+ // 1. 組合 Query String
105
+ $queryString = http_build_query($params);
106
+
107
+ // 2. AES-256-CBC 加密
108
+ $encrypted = openssl_encrypt(
109
+ $queryString,
110
+ 'AES-256-CBC',
111
+ $this->hashKey,
112
+ OPENSSL_RAW_DATA,
113
+ $this->hashIV
114
+ );
115
+
116
+ // 3. 轉十六進制
117
+ return bin2hex($encrypted);
118
+ }
119
+
120
+ /**
121
+ * AES-256-CBC 解密
122
+ */
123
+ public function decrypt(string $encryptedData): array
124
+ {
125
+ // 1. Hex 轉 Binary
126
+ $data = hex2bin($encryptedData);
127
+
128
+ // 2. AES-256-CBC 解密
129
+ $decrypted = openssl_decrypt(
130
+ $data,
131
+ 'AES-256-CBC',
132
+ $this->hashKey,
133
+ OPENSSL_RAW_DATA,
134
+ $this->hashIV
135
+ );
136
+
137
+ // 3. 解析 Query String
138
+ parse_str($decrypted, $result);
139
+
140
+ return $result;
141
+ }
142
+
143
+ /**
144
+ * 產生 TradeSha (SHA256)
145
+ */
146
+ public function tradeSha(string $tradeInfo): string
147
+ {
148
+ $raw = "HashKey={$this->hashKey}&{$tradeInfo}&HashIV={$this->hashIV}";
149
+ return strtoupper(hash('sha256', $raw));
150
+ }
151
+ }
152
+ ```
153
+
154
+ ### Python 加密範例
155
+
156
+ ```python
157
+ """NewebPay AES-256-CBC 加密"""
158
+
159
+ from Crypto.Cipher import AES
160
+ from Crypto.Util.Padding import pad, unpad
161
+ from urllib.parse import urlencode, parse_qs
162
+ import hashlib
163
+
164
+
165
+ class NewebPayEncryption:
166
+ def __init__(self, hash_key: str, hash_iv: str):
167
+ self.hash_key = hash_key.encode('utf-8')
168
+ self.hash_iv = hash_iv.encode('utf-8')
169
+
170
+ def encrypt(self, params: dict) -> str:
171
+ """AES-256-CBC 加密"""
172
+ # 1. 組合 Query String
173
+ query_string = urlencode(params)
174
+
175
+ # 2. AES-256-CBC 加密
176
+ cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
177
+ padded = pad(query_string.encode('utf-8'), AES.block_size)
178
+ encrypted = cipher.encrypt(padded)
179
+
180
+ # 3. 轉十六進制
181
+ return encrypted.hex()
182
+
183
+ def decrypt(self, encrypted_data: str) -> dict:
184
+ """AES-256-CBC 解密"""
185
+ # 1. Hex 轉 Binary
186
+ data = bytes.fromhex(encrypted_data)
187
+
188
+ # 2. AES-256-CBC 解密
189
+ cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
190
+ decrypted = unpad(cipher.decrypt(data), AES.block_size)
191
+
192
+ # 3. 解析 Query String
193
+ result = dict(parse_qs(decrypted.decode('utf-8')))
194
+ return {k: v[0] for k, v in result.items()}
195
+
196
+ def trade_sha(self, trade_info: str) -> str:
197
+ """產生 TradeSha (SHA256)"""
198
+ raw = f"HashKey={self.hash_key.decode()}&{trade_info}&HashIV={self.hash_iv.decode()}"
199
+ return hashlib.sha256(raw.encode('utf-8')).hexdigest().upper()
200
+ ```
201
+
202
+ ### CheckCode 驗證
203
+
204
+ 驗證回傳結果的 CheckCode:
205
+
206
+ ```php
207
+ <?php
208
+
209
+ function generateCheckCode(array $params, string $hashKey, string $hashIV): string
210
+ {
211
+ // 取出四個欄位
212
+ $checkParams = [
213
+ 'Amt' => $params['Amt'],
214
+ 'MerchantID' => $params['MerchantID'],
215
+ 'MerchantOrderNo' => $params['MerchantOrderNo'],
216
+ 'TradeNo' => $params['TradeNo'],
217
+ ];
218
+
219
+ // 排序 (A-Z)
220
+ ksort($checkParams);
221
+
222
+ // 組合字串
223
+ $paramStr = http_build_query($checkParams);
224
+
225
+ // 前後加上 HashIV 和 HashKey (注意順序)
226
+ $raw = "HashIV={$hashIV}&{$paramStr}&HashKey={$hashKey}";
227
+
228
+ // SHA256 + 轉大寫
229
+ return strtoupper(hash('sha256', $raw));
230
+ }
231
+ ```
232
+
233
+ ---
234
+
235
+ ## MPG 交易
236
+
237
+ ### 端點
238
+
239
+ ```
240
+ POST /MPG/mpg_gateway
241
+ ```
242
+
243
+ ### Post 參數
244
+
245
+ | 參數 | 類型 | 必填 | 說明 |
246
+ |------|------|------|------|
247
+ | `MerchantID` | String(15) | ✓ | 商店代號 |
248
+ | `TradeInfo` | String | ✓ | AES 加密後的交易資料 |
249
+ | `TradeSha` | String | ✓ | SHA256 驗證碼 |
250
+ | `Version` | String(5) | ✓ | 串接版本 `2.3` |
251
+ | `EncryptType` | Int(1) | 否 | 加密模式 `1`=AES/GCM |
252
+
253
+ ### TradeInfo 參數
254
+
255
+ | 參數 | 類型 | 必填 | 說明 |
256
+ |------|------|------|------|
257
+ | `MerchantID` | String(15) | ✓ | 商店代號 |
258
+ | `RespondType` | String(6) | ✓ | 回傳格式 `JSON` 或 `String` |
259
+ | `TimeStamp` | String(50) | ✓ | Unix 時間戳 (容許誤差 120 秒) |
260
+ | `Version` | String(5) | ✓ | 串接版本 `2.3` |
261
+ | `MerchantOrderNo` | String(30) | ✓ | 訂單編號 (唯一) |
262
+ | `Amt` | Int(10) | ✓ | 訂單金額 (新台幣整數) |
263
+ | `ItemDesc` | String(50) | ✓ | 商品資訊 |
264
+ | `LangType` | String(5) | 否 | 語系 `zh-tw`/`en`/`jp` |
265
+ | `TradeLimit` | Int(3) | 否 | 交易秒數限制 (60-900) |
266
+ | `ExpireDate` | String(10) | 否 | 繳費期限 `Ymd`,預設 7 天,最大 180 天 |
267
+ | `ReturnURL` | String(200) | 否 | 付款完成返回網址 |
268
+ | `NotifyURL` | String(200) | 否 | 背景通知網址 |
269
+ | `CustomerURL` | String(200) | 否 | 取號結果網址 |
270
+ | `ClientBackURL` | String(200) | 否 | 返回商店按鈕網址 |
271
+ | `Email` | String(50) | 否 | 付款人 Email |
272
+ | `EmailModify` | Int(1) | 否 | Email 可否修改 `1`=可 `0`=不可 |
273
+
274
+ ### 支付方式參數
275
+
276
+ | 參數 | 類型 | 說明 |
277
+ |------|------|------|
278
+ | `CREDIT` | Int(1) | 信用卡一次付清 `1`=啟用 |
279
+ | `APPLEPAY` | Int(1) | Apple Pay `1`=啟用 |
280
+ | `ANDROIDPAY` | Int(1) | Google Pay `1`=啟用 |
281
+ | `SAMSUNGPAY` | Int(1) | Samsung Pay `1`=啟用 |
282
+ | `LINEPAY` | Int(1) | LINE Pay `1`=啟用 |
283
+ | `InstFlag` | String(18) | 分期 `1`=全部, `3,6,12`=指定期數 |
284
+ | `CreditRed` | Int(1) | 紅利折抵 `1`=啟用 |
285
+ | `UNIONPAY` | Int(1) | 銀聯卡 `1`=啟用 |
286
+ | `CREDITAE` | Int(1) | 美國運通卡 `1`=啟用 |
287
+ | `WEBATM` | Int(1) | WebATM `1`=啟用 (限 49,999 元以下) |
288
+ | `VACC` | Int(1) | ATM 轉帳 `1`=啟用 (限 49,999 元以下) |
289
+ | `BankType` | String(26) | 指定銀行 `BOT`/`HNCB`/`KGI` |
290
+ | `CVS` | Int(1) | 超商代碼 `1`=啟用 (30-20,000 元) |
291
+ | `BARCODE` | Int(1) | 超商條碼 `1`=啟用 (20-40,000 元) |
292
+ | `ESUNWALLET` | Int(1) | 玉山 Wallet `1`=啟用 |
293
+ | `TAIWANPAY` | Int(1) | 台灣 Pay `1`=啟用 (限 49,999 元以下) |
294
+ | `BITOPAY` | Int(1) | BitoPay `1`=啟用 (100-49,999 元) |
295
+ | `CVSCOM` | Int(1) | 超商物流 `1`=取貨不付款 `2`=取貨付款 `3`=兩者 |
296
+ | `TWQR` | Int(1) | TWQR/簡單付 `1`=啟用 |
297
+ | `EZPWECHAT` | Int(1) | 簡單付微信 `1`=啟用 |
298
+ | `EZPALIPAY` | Int(1) | 簡單付支付寶 `1`=啟用 |
299
+
300
+ ### 信用卡記憶卡號
301
+
302
+ | 參數 | 類型 | 說明 |
303
+ |------|------|------|
304
+ | `TokenTerm` | String(20) | 付款人綁定資料 (會員編號/Email) |
305
+ | `TokenTermDemand` | Int(1) | 必填欄位 `1`=到期日+安全碼 `2`=到期日 `3`=安全碼 `4`=都不必填 |
306
+
307
+ ### PHP 範例
308
+
309
+ ```php
310
+ <?php
311
+
312
+ $encryption = new NewebPayEncryption($hashKey, $hashIV);
313
+
314
+ $params = [
315
+ 'MerchantID' => 'MS12345678',
316
+ 'RespondType' => 'JSON',
317
+ 'TimeStamp' => time(),
318
+ 'Version' => '2.3',
319
+ 'MerchantOrderNo' => 'ORDER' . time(),
320
+ 'Amt' => 1000,
321
+ 'ItemDesc' => '測試商品',
322
+ 'Email' => 'test@example.com',
323
+ 'CREDIT' => 1,
324
+ 'VACC' => 1,
325
+ 'NotifyURL' => 'https://your-site.com/notify',
326
+ 'ReturnURL' => 'https://your-site.com/return',
327
+ ];
328
+
329
+ $tradeInfo = $encryption->encrypt($params);
330
+ $tradeSha = $encryption->tradeSha($tradeInfo);
331
+
332
+ // 產生表單
333
+ $html = <<<HTML
334
+ <form method="post" action="https://core.newebpay.com/MPG/mpg_gateway">
335
+ <input type="hidden" name="MerchantID" value="{$params['MerchantID']}">
336
+ <input type="hidden" name="TradeInfo" value="{$tradeInfo}">
337
+ <input type="hidden" name="TradeSha" value="{$tradeSha}">
338
+ <input type="hidden" name="Version" value="2.3">
339
+ <button type="submit">前往付款</button>
340
+ </form>
341
+ HTML;
342
+
343
+ echo $html;
344
+ ```
345
+
346
+ ---
347
+
348
+ ## 單筆交易查詢
349
+
350
+ ### 端點
351
+
352
+ ```
353
+ POST /API/QueryTradeInfo
354
+ ```
355
+
356
+ ### 請求參數
357
+
358
+ | 參數 | 類型 | 必填 | 說明 |
359
+ |------|------|------|------|
360
+ | `MerchantID` | String(15) | ✓ | 商店代號 |
361
+ | `Version` | String(5) | ✓ | `1.3` |
362
+ | `RespondType` | String(6) | ✓ | `JSON` 或 `String` |
363
+ | `CheckValue` | String(255) | ✓ | 檢查碼 |
364
+ | `TimeStamp` | String(50) | ✓ | Unix 時間戳 |
365
+ | `MerchantOrderNo` | String(30) | ✓ | 商店訂單編號 |
366
+ | `Amt` | Int(10) | ✓ | 訂單金額 |
367
+
368
+ ### CheckValue 產生規則
369
+
370
+ ```php
371
+ <?php
372
+
373
+ function generateCheckValue(string $amt, string $merchantID, string $merchantOrderNo, string $hashKey, string $hashIV): string
374
+ {
375
+ // 1. 組合參數 (A-Z 排序)
376
+ $paramStr = "Amt={$amt}&MerchantID={$merchantID}&MerchantOrderNo={$merchantOrderNo}";
377
+
378
+ // 2. 前後加上 IV 和 Key
379
+ $raw = "IV={$hashIV}&{$paramStr}&Key={$hashKey}";
380
+
381
+ // 3. SHA256 + 轉大寫
382
+ return strtoupper(hash('sha256', $raw));
383
+ }
384
+ ```
385
+
386
+ ### 回應參數
387
+
388
+ | 參數 | 說明 |
389
+ |------|------|
390
+ | `Status` | `SUCCESS` 或錯誤碼 |
391
+ | `Message` | 訊息說明 |
392
+ | `Result` | 交易詳細資訊 |
393
+
394
+ ### Result 欄位
395
+
396
+ | 參數 | 說明 |
397
+ |------|------|
398
+ | `MerchantID` | 商店代號 |
399
+ | `Amt` | 交易金額 |
400
+ | `TradeNo` | 藍新交易序號 |
401
+ | `MerchantOrderNo` | 商店訂單編號 |
402
+ | `TradeStatus` | 交易狀態 `0`=未付款 `1`=成功 `2`=失敗 `3`=取消 `6`=退款 |
403
+ | `PaymentType` | 支付方式 |
404
+ | `CreateTime` | 建立時間 |
405
+ | `PayTime` | 付款時間 |
406
+ | `CheckCode` | 檢核碼 |
407
+ | `FundTime` | 預計撥款日 |
408
+
409
+ ### 信用卡專屬欄位
410
+
411
+ | 參數 | 說明 |
412
+ |------|------|
413
+ | `RespondCode` | 金融機構回應碼 |
414
+ | `Auth` | 授權碼 |
415
+ | `ECI` | 3D 驗證值 (`1`,`2`,`5`,`6`=3D 交易) |
416
+ | `CloseAmt` | 請款金額 |
417
+ | `CloseStatus` | 請款狀態 `0`=未請款 `1`=等待 `2`=處理中 `3`=完成 |
418
+ | `BackBalance` | 可退款餘額 |
419
+ | `BackStatus` | 退款狀態 `0`=未退款 `1`=等待 `2`=處理中 `3`=完成 |
420
+ | `Card6No` | 卡號前六碼 |
421
+ | `Card4No` | 卡號後四碼 |
422
+ | `Inst` | 分期期別 |
423
+ | `InstFirst` | 首期金額 |
424
+ | `InstEach` | 每期金額 |
425
+ | `AuthBank` | 收單機構 |
426
+
427
+ ---
428
+
429
+ ## 取消授權
430
+
431
+ ### 端點
432
+
433
+ ```
434
+ POST /API/CreditCard/Cancel
435
+ ```
436
+
437
+ ### 請求參數
438
+
439
+ | 參數 | 類型 | 必填 | 說明 |
440
+ |------|------|------|------|
441
+ | `MerchantID_` | String(10) | ✓ | 商店代號 |
442
+ | `PostData_` | Text | ✓ | AES 加密資料 |
443
+
444
+ ### PostData_ 內容
445
+
446
+ | 參數 | 類型 | 必填 | 說明 |
447
+ |------|------|------|------|
448
+ | `RespondType` | String(5) | ✓ | `JSON` 或 `String` |
449
+ | `Version` | String(5) | ✓ | `1.0` |
450
+ | `Amt` | Int(10) | ✓ | 取消金額 (需與授權金額相同) |
451
+ | `MerchantOrderNo` | String(30) | + | 訂單編號 (二擇一) |
452
+ | `TradeNo` | String(17) | + | 藍新交易序號 (二擇一) |
453
+ | `IndexType` | Int(1) | ✓ | `1`=用訂單編號 `2`=用交易序號 |
454
+ | `TimeStamp` | String(30) | ✓ | Unix 時間戳 |
455
+
456
+ ---
457
+
458
+ ## 請退款/取消請退款
459
+
460
+ ### 端點
461
+
462
+ ```
463
+ POST /API/CreditCard/Close
464
+ ```
465
+
466
+ ### 功能說明
467
+
468
+ | 功能編號 | 功能 | CloseType | Cancel |
469
+ |----------|------|-----------|--------|
470
+ | B031 | 請款 | `1` | - |
471
+ | B032 | 退款 | `2` | - |
472
+ | B033 | 取消請款 | `1` | `1` |
473
+ | B034 | 取消退款 | `2` | `1` |
474
+
475
+ ### 請求參數
476
+
477
+ | 參數 | 類型 | 必填 | 說明 |
478
+ |------|------|------|------|
479
+ | `MerchantID_` | String(15) | ✓ | 商店代號 |
480
+ | `PostData_` | Text | ✓ | AES 加密資料 |
481
+
482
+ ### PostData_ 內容
483
+
484
+ | 參數 | 類型 | 必填 | 說明 |
485
+ |------|------|------|------|
486
+ | `RespondType` | String(5) | ✓ | `JSON` 或 `String` |
487
+ | `Version` | String(5) | ✓ | `1.1` |
488
+ | `Amt` | Int(10) | ✓ | 請退款金額 |
489
+ | `MerchantOrderNo` | String(30) | ✓ | 訂單編號 |
490
+ | `TimeStamp` | String(30) | ✓ | Unix 時間戳 |
491
+ | `IndexType` | Int(1) | ✓ | `1`=用訂單編號 `2`=用交易序號 |
492
+ | `TradeNo` | String(20) | ✓ | 藍新交易序號 |
493
+ | `CloseType` | Int(1) | ✓ | `1`=請款 `2`=退款 |
494
+ | `Cancel` | Int(1) | 否 | `1`=取消請款/退款 |
495
+
496
+ ### 退款限制
497
+
498
+ | 交易類型 | 請款 | 退款 |
499
+ |----------|------|------|
500
+ | 一次付清 | 整筆/部分 | 整筆/部分 |
501
+ | 分期付款 | 整筆 | 整筆 |
502
+ | 紅利折抵 | 整筆 | 整筆 |
503
+ | 銀聯卡 | 整筆 | 整筆/部分 |
504
+
505
+ ---
506
+
507
+ ## 電子錢包退款
508
+
509
+ ### 端點
510
+
511
+ ```
512
+ POST /API/EWallet/refund
513
+ ```
514
+
515
+ ### 各錢包退款規則
516
+
517
+ | 錢包 | 退款期限 | 部分退款 | 備註 |
518
+ |------|----------|----------|------|
519
+ | 玉山 Wallet | 89 天 | ✓ | 交易完成 10 分鐘後 |
520
+ | 台灣 Pay | 29 天 | ✗ | 僅全額退款 |
521
+ | LINE Pay | 60 天 | ✓ | |
522
+ | TWQR | 89 天 | ✓ | 從請款日起算 |
523
+ | 支付寶/微信 | 89 天 | ✓ | |
524
+
525
+ ### 請求參數
526
+
527
+ | 參數 | 類型 | 必填 | 說明 |
528
+ |------|------|------|------|
529
+ | `UID_` | String(15) | ✓ | 商店代號 |
530
+ | `Version_` | String(5) | ✓ | `1.1` |
531
+ | `EncryptData_` | Text | ✓ | AES 加密資料 |
532
+ | `RespondType_` | String(15) | ✓ | `JSON` |
533
+ | `HashData_` | Text | ✓ | SHA256 雜湊 |
534
+
535
+ ### EncryptData_ 內容
536
+
537
+ | 參數 | 類型 | 必填 | 說明 |
538
+ |------|------|------|------|
539
+ | `MerchantOrderNo` | String(30) | ✓ | 訂單編號 |
540
+ | `Amount` | Int(10) | ✓ | 退款金額 |
541
+ | `TimeStamp` | String(50) | ✓ | Unix 時間戳 |
542
+ | `PaymentType` | String | ✓ | 付款方式 (見下表) |
543
+
544
+ ### PaymentType 對應
545
+
546
+ | 錢包 | PaymentType |
547
+ |------|-------------|
548
+ | 玉山 Wallet | `ESUNWALLET` |
549
+ | LINE Pay | `LINEPAY` |
550
+ | 台灣 Pay | `TAIWANPAY` |
551
+ | TWQR | `TWQR` |
552
+ | 支付寶 | `EZPALIPAY` |
553
+ | 微信 | `EZPWECHAT` |
554
+
555
+ ---
556
+
557
+ ## 付款結果通知
558
+
559
+ ### 通知流程
560
+
561
+ 藍新會 POST 加密資料到 `NotifyURL` 和 `ReturnURL`。
562
+
563
+ ### 通知參數
564
+
565
+ | 參數 | 說明 |
566
+ |------|------|
567
+ | `Status` | `SUCCESS` 或錯誤碼 |
568
+ | `MerchantID` | 商店代號 |
569
+ | `TradeInfo` | AES 加密的交易結果 |
570
+ | `TradeSha` | SHA256 驗證碼 |
571
+ | `Version` | 串接版本 |
572
+
573
+ ### TradeInfo 解密後內容
574
+
575
+ | 參數 | 說明 |
576
+ |------|------|
577
+ | `Status` | 交易狀態 |
578
+ | `Message` | 交易訊息 |
579
+ | `MerchantID` | 商店代號 |
580
+ | `Amt` | 交易金額 |
581
+ | `TradeNo` | 藍新交易序號 |
582
+ | `MerchantOrderNo` | 訂單編號 |
583
+ | `PaymentType` | 支付方式 |
584
+ | `PayTime` | 付款時間 |
585
+ | `IP` | 付款人 IP |
586
+ | `EscrowBank` | 款項保管銀行 |
587
+
588
+ ### 處理範例
589
+
590
+ ```php
591
+ <?php
592
+
593
+ // 接收通知
594
+ $status = $_POST['Status'] ?? '';
595
+ $tradeInfo = $_POST['TradeInfo'] ?? '';
596
+ $tradeSha = $_POST['TradeSha'] ?? '';
597
+
598
+ // 驗證 TradeSha
599
+ $encryption = new NewebPayEncryption($hashKey, $hashIV);
600
+ $calculatedSha = $encryption->tradeSha($tradeInfo);
601
+
602
+ if ($tradeSha !== $calculatedSha) {
603
+ echo 'TradeSha Error';
604
+ exit;
605
+ }
606
+
607
+ // 解密
608
+ $data = $encryption->decrypt($tradeInfo);
609
+
610
+ // 檢查交易狀態
611
+ if ($data['Status'] === 'SUCCESS') {
612
+ // 交易成功,更新訂單狀態
613
+ updateOrderStatus($data['MerchantOrderNo'], 'paid', $data);
614
+ }
615
+
616
+ // 回應 (藍新不要求特定回應)
617
+ echo 'OK';
618
+ ```
619
+
620
+ ---
621
+
622
+ ## 錯誤碼對照表
623
+
624
+ ### 常見錯誤碼
625
+
626
+ | 錯誤碼 | 說明 | 備註 |
627
+ |--------|------|------|
628
+ | `MPG01002` | 時間戳記不可空白 | TimeStamp |
629
+ | `MPG01009` | 商店代號不可空白 | MerchantID |
630
+ | `MPG01012` | 訂單編號錯誤 | 限英數字底線,30 字 |
631
+ | `MPG01015` | 金額錯誤 | Amt |
632
+ | `MPG01023` | TradeInfo 不可空白 | |
633
+ | `MPG01024` | TradeSha 不可空白 | |
634
+ | `MPG02001` | 檢查碼錯誤 | CheckValue |
635
+ | `MPG02002` | 未啟用金流服務 | |
636
+ | `MPG02003` | 支付方式未啟用 | |
637
+ | `MPG03004` | 商店已暫停 | |
638
+ | `MPG03008` | 訂單編號重複 | |
639
+ | `MPG03009` | 交易失敗 | SHA256 驗證失敗 |
640
+ | `MPG05002` | 信用卡卡號錯誤 | |
641
+ | `MPG05005` | 警示交易 | |
642
+
643
+ ### 交易狀態碼 (TradeStatus)
644
+
645
+ | 狀態 | 說明 |
646
+ |------|------|
647
+ | `0` | 未付款 |
648
+ | `1` | 付款成功 |
649
+ | `2` | 付款失敗 |
650
+ | `3` | 取消付款 |
651
+ | `6` | 已退款 |
652
+ | `9` | 付款中 (待銀行確認) |
653
+
654
+ ### 收單機構代碼 (AuthBank)
655
+
656
+ | 代碼 | 銀行 |
657
+ |------|------|
658
+ | `Esun` | 玉山銀行 |
659
+ | `Taishin` | 台新銀行 |
660
+ | `CTBC` | 中國信託 |
661
+ | `NCCC` | 聯合信用卡中心 |
662
+ | `CathayBK` | 國泰世華 |
663
+ | `Citibank` | 花旗銀行 |
664
+ | `UBOT` | 聯邦銀行 |
665
+ | `SKBank` | 新光銀行 |
666
+ | `Fubon` | 富邦銀行 |
667
+ | `FirstBank` | 第一銀行 |
668
+ | `LINEBank` | 連線商業銀行 |
669
+ | `SinoPac` | 永豐銀行 |
670
+
671
+ ---
672
+
673
+ ## 官方資源
674
+
675
+ - **官方網站**: https://www.newebpay.com/
676
+ - **API 文件**: https://www.newebpay.com/website/Page/content/download_api
677
+ - **技術客服**: 02-2162-2005