taiwan-payment-skill 1.5.5 → 1.5.6

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.
@@ -75,6 +75,14 @@ def _canonical(payload: Dict[str, Any]) -> str:
75
75
  return json.dumps(ordered, separators=(',', ':'), ensure_ascii=False)
76
76
 
77
77
 
78
+ def java_urlencode(text: str) -> str:
79
+ """Java URLEncoder 規則(手冊附錄 3:check_value 必須符合 Java urlencode)。
80
+
81
+ 空白編成 `+`、`*` 不編碼、`~` 編成 `%7E`;Python 的 quote 三者都不同。
82
+ """
83
+ return urllib.parse.quote_plus(text, safe='*').replace('~', '%7E')
84
+
85
+
78
86
  def make_check_value(payload: Dict[str, Any], sha2_key: str) -> str:
79
87
  """產生 check_value。
80
88
 
@@ -84,7 +92,7 @@ def make_check_value(payload: Dict[str, Any], sha2_key: str) -> str:
84
92
  `HashKey=...&參數&HashIV=...` 的前後包夾。
85
93
  值為 null 的參數不參與簽名(官方明註),本函式已於 build 階段排除。
86
94
  """
87
- encoded = urllib.parse.quote(_canonical(payload), safe='')
95
+ encoded = java_urlencode(_canonical(payload))
88
96
  return hashlib.sha256((encoded + sha2_key).encode('utf-8')).hexdigest()
89
97
 
90
98
 
@@ -94,7 +102,7 @@ def make_rsamsg(payload: Dict[str, Any], public_key_pem: str) -> str:
94
102
  raise RuntimeError('需要 cryptography 套件:pip install cryptography')
95
103
 
96
104
  key = serialization.load_pem_public_key(public_key_pem.encode('utf-8'))
97
- data = urllib.parse.quote(_canonical(payload), safe='').encode('utf-8')
105
+ data = java_urlencode(_canonical(payload)).encode('utf-8')
98
106
 
99
107
  out = bytearray()
100
108
  for i in range(0, len(data), RSA_ENCRYPT_CHUNK):
@@ -288,7 +296,7 @@ def _self_test() -> int:
288
296
  failed = 0
289
297
  print('紅陽官方測試向量驗證')
290
298
 
291
- encoded = urllib.parse.quote(_canonical(payload), safe='')
299
+ encoded = java_urlencode(_canonical(payload))
292
300
  ok = encoded == expected_encoded
293
301
  failed += not ok
294
302
  print(f' [{"PASS" if ok else "FAIL"}] urlencode 結果與手冊逐字相同')
@@ -304,6 +312,12 @@ def _self_test() -> int:
304
312
  print(f' 期望 {expected_check}')
305
313
  print(f' 實得 {got}')
306
314
 
315
+ # 手冊附錄 3 的 Java URLEncoder 欄:空白 +、~ %7E、* 不編、/ %2F
316
+ got = java_urlencode('a b~c*d/e')
317
+ ok = got == 'a+b%7Ec*d%2Fe'
318
+ failed += not ok
319
+ print(f' [{"PASS" if ok else "FAIL"}] 特殊字元依 Java URLEncoder 編碼(實得 {got})')
320
+
307
321
  # send_time 格式:毫秒在最前面、日期在最後
308
322
  st = build_send_time(datetime(2023, 9, 27, 16, 21, 34, 585_000))
309
323
  ok = st == '585342116' + '20230927'
@@ -291,7 +291,86 @@ GET https://[Host]/platform/inquiry?platform_order_ids={id1},{id2}
291
291
 
292
292
  > 官方範例中第二筆退款紀錄沒有 `refund_order_id`——舊資料可能缺欄,解析時別假設必存在。
293
293
 
294
- 另有**交易撥款檔 R File**(Reimburse File)供對帳,欄位格式待補。
294
+ ### 5.9 店家撥款檔 R File(Reimburse File)
295
+
296
+ 線上支付與線下 POS 的 R 檔格式相同(兩份官方頁面欄位逐一一致)。
297
+
298
+ **取得方式**
299
+
300
+ - 街口上傳至街口端 FTP Server;須向業務窗口提供抓檔的來源 IP,審核通過後才給正式/測試 FTP 連線資訊
301
+ - 依請款週期產生,每日 06:00 後可下載
302
+ - 檔名:一般店 `M_ReimburseReport_{店家統編}_{產生日 yyyyMMdd}_R_P.csv`;平台店(僅線上支付頁列出)`…_R_P{Number}.csv`
303
+ - CSV,欄位以 `,` 分隔,每列以 `0d0a`(CRLF)結尾
304
+ - 金額欄一律兩位小數(含小數點),不帶 `+`/`-`;正負由類別欄(`J`/`K`)表示
305
+
306
+ **檔頭 `H`**:資料類別 `H`、檔案日期 `yyyyMMdd`、檔案時間 `HHmm`、預計撥款日期 `yyyyMMdd`
307
+
308
+ **明細 `I`**(依序)
309
+
310
+ | # | 欄位 | 型態(長) | 說明 |
311
+ |---|---|---|---|
312
+ | 1 | 資料類別 | String(1) | `I` |
313
+ | 2 | 交易時間 | String(19) | `TransactionTime`,`yyyy/MM/dd HH:mm:ss` |
314
+ | 3 | 店舖代碼 | String(36) | `StoreID` |
315
+ | 4 | 店舖名稱 | String(70) | 可含中文 |
316
+ | 5 | 交易行為 | String(1) | `1` 支付、`3` 點餐、`5` 外送 |
317
+ | 6 | 交易類別 | String(1) | `J` 付款、`K` 退款 |
318
+ | 7 | 街口端交易序號 | String(50) | `PurchaseNo`(tradeNo) |
319
+ | 8 | 廠商端交易序號 | String(50) | `platform_order_id`;從街口端發起的退款沒有序號,補空白 |
320
+ | 9 | 訂單金額 | Decimal(10) | `BaseAmount` |
321
+ | 10 | 街口配送費 | Decimal(10) | `DeliveryFee`,僅街口配送的外送交易,否則空白 |
322
+ | 11 | 店家街口券折抵 | Decimal(10) | `CouponStoreRedeem`,店家負擔,未使用則空白 |
323
+ | 12 | 官方街口券折抵 | Decimal(10) | `CouponJKORedeem`,街口負擔,未使用則空白 |
324
+ | 13 | 街口幣折抵 | Decimal(10) | `Redeem` |
325
+ | 14 | 支付金額 | Decimal(10) | `PayAmount` = 訂單金額 − 店家/官方券折抵 − 街口幣折抵 + 街口配送費 |
326
+ | 15 | 店家街口幣回饋 | Decimal(8) | 店家負擔,無回饋則空白 |
327
+ | 16 | 支付請款金額 | Decimal(10) | 支付金額 − 支付手續費 − 店家街口幣回饋 − 點餐/外送服務費 − 街口配送費 |
328
+ | 17 | 支付手續費 | Decimal(8) | (支付金額 − 街口配送費)× 支付費率 |
329
+ | 18 | 點餐/外送服務費 | Decimal(8) | 訂單金額 × 點餐/外送費率,非此類交易空白 |
330
+ | 19 | 街口幣折抵請款金額 | Decimal(10) | 街口幣折抵 − 街口幣折抵手續費 |
331
+ | 20 | 街口幣折抵手續費 | Decimal(8) | 街口幣折抵 × 折抵費率 |
332
+ | 21 | 官方街口券折抵請款金額 | Decimal(10) | 官方券折抵 − 官方券折抵手續費 |
333
+ | 22 | 官方街口券折抵手續費 | Decimal(8) | 官方券折抵 × 折抵費率 |
334
+ | 23–25 | 保留欄位 ×3 | String(30) | 補空白 |
335
+
336
+ **檔尾 `T`**(依序)
337
+
338
+ | # | 欄位 | 型態(長) | 說明 |
339
+ |---|---|---|---|
340
+ | 1 | 資料類別 | String(1) | `T` |
341
+ | 2 | 總筆數 | Decimal(8) | 明細筆數 |
342
+ | 3 | 訂單總金額 | Decimal(12) | |
343
+ | 4 | 支付總金額 | Decimal(12) | |
344
+ | 5 | 支付總手續費 | Decimal(8) | 支付手續費 + 店家回饋街口幣 + 點餐/外送服務費 |
345
+ | 6 | 支付總請款金額 | Decimal(12) | |
346
+ | 7 | 街口幣折抵總金額 | Decimal(12) | 紅利月結店家一律 `0.00` |
347
+ | 8 | 街口幣折抵總手續費 | Decimal(8) | 紅利月結店家一律 `0.00` |
348
+ | 9 | 街口幣折抵總請款金額 | Decimal(12) | |
349
+ | 10 | 官方街口券折抵總金額 | Decimal(12) | 紅利月結店家一律 `0.00` |
350
+ | 11 | 官方街口券折抵總手續費 | Decimal(8) | 紅利月結店家一律 `0.00` |
351
+ | 12 | 官方街口券折抵總請款金額 | Decimal(12) | |
352
+ | 13 | 店家街口券折抵總金額型別 | String(1) | `J` 退還店家、`K` 向店家收取 |
353
+ | 14 | 店家街口券折抵總金額 | Decimal(12) | 全數店家負擔 |
354
+ | 15 | 街口券發送費 | Decimal(12) | `SendingFee` 加總 |
355
+ | 16 | 街口券折抵費型別 | String(1) | `J` 退還店家、`K` 向店家收取 |
356
+ | 17 | 街口券折抵費 | Decimal(12) | `UsageFee` 加總 |
357
+ | 18 | 調帳金額型別 | String(1) | `J` 調帳補匯、`K` 調帳扣回 |
358
+ | 19 | 調帳金額 | Decimal(8) | |
359
+ | 20 | 匯費 | Decimal(8) | 銀行匯款手續費 |
360
+ | 21 | 總撥款金額 | Decimal(12) | 支付總請款 + 街口幣總請款 + 官方券總請款 + 調帳 − 街口券發送費 − 街口券折抵費 − 匯費,已四捨五入到整數 |
361
+ | 22–24 | 保留欄位 ×3 | String(30) | 補空白 |
362
+
363
+ 官方範例:
364
+
365
+ ```
366
+ H,20190708,0500,2019070900
367
+ I,2019/07/07 12:00:00,d7120db2-8c76-4124-bf08-02e5b775d8fe,哈拉股份有限公司,1,J,J0026910118070413C4,19070710026C8N8,1000.00,,200.00,, 200.00,600.00,,586.80,13.20,,195.60,4.40,,,,,,
368
+ I,2019/07/07 12:30:00, d7120db2-8c76-4124-bf08-02e5b775d8fe,哈拉股份有限公司,1,J,J0026910118070413C5,190707214361GPU,1000.00,,,200.00, 200.00,600.00,,586.80,13.20,,195.60,4.40,195.60,4.40,,,,
369
+ I,2019/07/07 12:55:20,d7120db2-8c76-4124-bf08-02e5b775d8fe,哈拉股份有限公司,1, K,K0026910118070413C4001,,1000.00,,,,200.00,800.00,,782.40,17.60,,195.60,4.40,,,,,,
370
+ T,3,2000.00,400.00,8.80,391.20,200.00,4.40,195.60,200.00,4.40,195.60, K,200.00,1.00,K,2.00,J,0.00,5.00,774.40,,,,
371
+ ```
372
+
373
+ > ⚠️ 官方範例與欄位表有出入,解析時要寬鬆:檔頭預計撥款日期寫成 10 碼(`2019070900`,表定 8 碼);部分欄位前帶空白(`, 200.00`、`, K`),先 `trim` 再判斷。
295
374
 
296
375
  ## 6. 授權扣款 Authorized Payment — 完整規格
297
376
 
@@ -445,7 +524,7 @@ Response 的 `result_object` 與 OnlinePay 的 `result_url` 同構(`tradeNo`
445
524
 
446
525
  `POST https://pos.jkopay.com/{系統方名稱}/Payment`
447
526
 
448
- 端點:付款 / 取消 / 退款 / 查詢 / 店家撥款檔(R 檔)。
527
+ 端點:付款 / 取消 / 退款 / 查詢 / 店家撥款檔(R 檔,格式見 §5.9)。
449
528
 
450
529
  ### 簽章(與線上支付完全不同)
451
530
 
@@ -543,7 +622,7 @@ Response 另含 `RefundTradeNo`、`RefundTradeTime`、`IsRep`、`PaymentType`、
543
622
 
544
623
  > 對帳程式若用同一個函式處理折抵金額,跨模組時金額會反號。建議在解析層就依來源正規化,不要在計算層才處理。
545
624
 
546
- ## 9. inApp 第三方服務 — OAuth / JOP Gateway
625
+ ## 9. inApp 第三方服務 — OAuth / JOP Gateway / Web SDK
547
626
 
548
627
  給 ISV 業者取得街口使用者授權資料用,**網域與支付 API 完全不同**:
549
628
 
@@ -592,6 +671,30 @@ Response 另含 `RefundTradeNo`、`RefundTradeTime`、`IsRep`、`PaymentType`、
592
671
 
593
672
  OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-360` Auth Code 過期、`OA-999` 系統異常;`UP-001` 成功、`UP-360` Auth Code 過期、`UP-460` **Access Token 過期**、`UP-999`;通用 `205` 參數錯誤、`405` 權限不足、`999` 網關異常。
594
673
 
674
+ ### Web SDK(`@jkos/openweb-bridge`)
675
+
676
+ 在街口 App 的 webview 內呼叫原生能力(授權、導航欄、路由、介面交互),全域物件為 `jkos`。
677
+
678
+ **版本與載入**(官方「SDK 版本」頁)
679
+
680
+ | 版本 | UMD | CJS | 變動 | 上版日 |
681
+ |---|---|---|---|---|
682
+ | 2.0.7 | `https://upkg.jkos.com/openweb-bridge/v2.0.7/jkos.umd.js` | `@jkos/openweb-bridge@2.0.7-prod` | 新增 `close` | 2022/08/10 |
683
+ | 2.0.6 | `…/v2.0.6/jkos.umd.js` | `@jkos/openweb-bridge@2.0.6-prod` | 新增 `setNavRightButton`、`setPullRefreshOn` | 2022/02/14 |
684
+ | 2.0.4 | `…/v2.0.4/jkos.umd.js` | `@jkos/openweb-bridge@2.0.4-prod` | 新增 `showModal` | 2021/11/16 |
685
+ | 2.0.3 | `…/v2.0.3/jkos.umd.js` | `@jkos/openweb-bridge@2.0.3-prod` | 新增 `openBrowser`、`redirectMaintainPage` | 2021/09/30 |
686
+ | 2.0.2 | `…/v2.0.2/jkos.umd.js` | `@jkos/openweb-bridge@2.0.2-prod` | `setNavRightButton` 我的按鈕 onClick | 2021/09/14 |
687
+ | 2.0.1 | `…/v2.0.1/jkos.umd.js` | `@jkos/openweb-bridge@2.0.1-prod` | 修正取得環境資訊 | 2021/09/05 |
688
+
689
+ - npm 套件在街口自有 registry:`https://npmjs.jkos.com/-/web/detail/@jkos/openweb-bridge`
690
+ - ⚠️ **v2.0.6 與先前版本不相容**:使用 v2.0.4(含)以下者,升級前須先聯絡街口窗口
691
+ - 文件另有 v2.0.8 與 Next 兩組 API 頁面,但版本表未列其 UMD/套件位址;官方未標示建議版本,採用前向街口窗口確認
692
+
693
+ **Next 版 API**:`getAuthCode`(喚起原生授權頁取得 auth code,接 §9 OAuth)、`setNavTitle`、`setNavBackground`、`setNavLeftButton`、`setNavRightButton`、`clearNavRightButton`、`openBrowser`、`redirectMaintainPage`、`close`、`showModal`、`setPullRefreshOn`/`setPullRefreshOff`。
694
+ 呼叫形式 `jkos.xxx(data, callback)`,callback 收 `{ error, errorMessage }`,也可改用 async/await。
695
+
696
+ **SDK 錯誤碼**:`0` 成功、`15` App 版本不支援該函式版本、`16` 格式錯誤、`17` 須在支援的街口 webview 入口開啟、`18` 無法取得 App 環境資訊、`19` App 版本找不到該函式、`206` 無效的 ClientID、`207` 無效的 Scope。
697
+
595
698
  ## 10. 統一錯誤代碼表(線下 POS)
596
699
 
597
700
  `StatusCode`,共 33 個代碼。**這是街口唯一一份「統一」錯誤碼表**,掛在 POS 模組下。
@@ -708,13 +811,11 @@ OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-
708
811
 
709
812
  ## 12. 仍待補
710
813
 
711
- 五大模組的 API 皆已擷取,剩餘為週邊項目:
712
-
713
- | 待補項目 | 優先 | 備註 |
714
- |---|---|---|
715
- | R File(店家撥款檔)欄位格式 | 中 | 線上支付與 POS 皆有此檔,對帳需要 |
716
- | Web SDK | 低 | 版本多(v2.0.2–v2.0.8 + Next),需先確認採用版本 |
717
- | 街口幣查詢 API | — | **官方尚未提供**,僅先公布簽章格式 |
814
+ | 待補項目 | 備註 |
815
+ |---|---|
816
+ | 街口幣查詢 API | **官方尚未提供**,僅先公布簽章格式 |
817
+ | Web SDK v2.0.8/Next 的載入位址與建議版本 | 官方版本表只列到 2.0.7,需向街口窗口確認 |
818
+ | R 檔 FTP 連線資訊 | 須提供來源 IP 給業務窗口審核後才提供 |
718
819
 
719
820
  ## 13. 來源
720
821
 
@@ -724,6 +825,10 @@ OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-
724
825
  - 加簽加密說明 — `…/線上支付onlinepay/串接說明/加簽加密說明`
725
826
  - 訂單創建 Entry API — `…/線上支付onlinepay/api列表/訂單創建-api`
726
827
  - 代碼意義 API Response Code — `…/線上支付onlinepay/api列表/代碼意義`
828
+ - 店家撥款檔 R 檔(線上支付)— `…/線上支付onlinepay/api列表/店家撥款檔r檔`
829
+ - 店家撥款檔 R 檔(線下 POS)— `…/線下交易pos/api列表/店家撥款檔r檔`
830
+ - Web SDK 版本 — https://open-doc.jkos.com/?docs=inapp-第三方服務/web-sdk/sdk-環境版本
831
+ - Web SDK Next — `…/inapp-第三方服務/web-sdk/next`(基礎開放能力、介面交互、按鈕、錯誤代碼)
727
832
  - 授權扣款 Authorized Payment — https://open-doc.jkos.com/?docs=授權扣款-authorized-payment
728
833
  - 授權創建 Binding — `…/授權扣款-authorized-payment/api列表-api-lists/授權綁定創建-authorization-binding`
729
834
  - 授權綁定結果通知 CallBack — `…/api列表-api-lists/授權綁定結果通知-authorization-callback`
@@ -101,7 +101,7 @@ Form POST,`application/x-www-form-urlencoded`。
101
101
  | `IgnorePayment` | String(100) | `ChoosePayment=ALL` 時隱藏特定付款方式,多筆以 `#` 分隔 |
102
102
  | `DeviceSource` | String(10) | 空值=預設版型;`APP`=App 版型 |
103
103
  | `PlatformID` | String(10) | 平台商代號。**有帶此參數時,檢查碼須用平台商的 HashKey/HashIV 計算** |
104
- | `HoldTradeAMT` | Int | `0`=不延遲撥款(預設);`1`=延遲撥款,需另呼叫「會員申請撥款/退款」API。**不適用信用卡** |
104
+ | `HoldTradeAMT` | Int | `0`=不延遲撥款(預設);`1`=延遲撥款,需另呼叫「會員申請撥款/退款」API(`Cashier/Capture`,見第 5 節)。**不適用信用卡** |
105
105
  | `UseRedeem` | String(1) | `Y`/`N`,是否可用購物金/紅包折抵 |
106
106
  | `Remark` / `ItemURL` | String | 備註 / 商品銷售網址 |
107
107
  | `ChooseSubPayment` | String(20) | 付款子項目(如 `TAISHIN`) |
@@ -226,6 +226,31 @@ def gen_check_mac_value(params: dict, hash_key: str, hash_iv: str) -> str:
226
226
  - 已關帳的信用卡訂單**不適用**,請用「信用卡關帳/退刷/取消/放棄」
227
227
  - 微信支付已撥款者無法用 API 退款,僅能人工處理(洽客服 02-2655-0115)
228
228
 
229
+ ### 會員申請撥款/退款 `Cashier/Capture`
230
+
231
+ 延遲撥款(`HoldTradeAMT=1`)的交易付款後,呼叫此 API 讓歐付寶撥款到會員帳戶,並可同時退款給買方(《全方位金流介接技術文件》第 13 章,p.41–42)。
232
+ 非延遲撥款的交易改用 `AioChargeback`;**信用卡交易不適用**。
233
+
234
+ - 正式:`https://payment.opay.tw/Cashier/Capture`
235
+ - 測試:`https://payment-stage.opay.tw/Cashier/Capture`
236
+ - Server POST,CheckMacValue 同第 4 節
237
+
238
+ | 參數 | 型態 | 必填 | 說明 |
239
+ |------|------|:---:|------|
240
+ | `MerchantID` | String(10) | ● | 會員編號 |
241
+ | `MerchantTradeNo` | String(64) | ● | 建立訂單時的會員交易編號 |
242
+ | `CheckMacValue` | String | ● | |
243
+ | `CaptureAMT` | Int | ● | 申請撥款金額 |
244
+ | `UserRefundAMT` | Int | ● | 退款給買方的金額,不退款帶 `0`;範圍 0~訂單金額。**`CaptureAMT + UserRefundAMT` 須等於訂單金額** |
245
+ | `PlatformID` | String(10) | | 專案合作平台商代號;一般會員帶空值 |
246
+ | `UpdatePlatformChargeFee` | String(1) | | `Y` 更改訂單的平台商手續費,預設 `N`;僅平台商使用 |
247
+ | `PlatformChargeFee` | Int | | `UpdatePlatformChargeFee=Y` 時帶,範圍 0~原手續費 |
248
+ | `Remark` | String(30) | | 備註 |
249
+
250
+ 實際撥款金額 = 訂單金額 − `UserRefundAMT` − 必要手續費。
251
+
252
+ 回應以 `參數=值&…` 直接回傳:`MerchantID`、`MerchantTradeNo`、`TradeNo`(String(20))、`RtnCode`(`1` 成功,其餘失敗)、`RtnMsg`、`AllocationDate`(預計撥款日 `yyyy-MM-dd`)。
253
+
229
254
  ### 其他端點
230
255
 
231
256
  | 功能 | 路徑 |
@@ -266,8 +291,7 @@ def gen_check_mac_value(params: dict, hash_key: str, hash_iv: str) -> str:
266
291
  | 會員 Open ID API | https://www.opay.tw/Content/files/O_Pay_041.pdf |
267
292
  | 電子發票 B2C / B2B / 離線 | 見 [../../taiwan-invoice/references/OPAY_API_REFERENCE.md](../../taiwan-invoice/references/OPAY_API_REFERENCE.md) |
268
293
 
269
- ## 8. 待驗證
294
+ ## 8. 備註與待驗證
270
295
 
271
296
  - POS、微信公眾號文件標註「若要串接使用請洽歐付寶客服」,可能需額外開通
272
- - 歐付寶物流 API 未出現在官方文件總覽頁;社群教學顯示存在,端點與參數待確認
273
- - 「會員申請撥款/退款」API(延遲撥款情境)的完整參數本次未擷取
297
+ - 歐付寶沒有公開物流 API:官方文件總覽(2026-09-21 修訂版,2026-09-24 查核)只列金流、電子發票、Open ID、平台綁定、直播主收款網址
@@ -142,7 +142,7 @@ rsamsg → Base64 decode(URL-safe:- _) → 以「公鑰」分段解密
142
142
  > ⚠️ **ASCII 排序是強制的**,手冊在兩處重複警告「請務必將 head 與 body 參數進行 ASCII 排序,以免加密失敗」。
143
143
  > ⚠️ SHA2 密鑰是**直接串接在 URLEncode 後字串的尾端**,不是 ECPay 那種 `HashKey=…&…&HashIV=…` 前後包夾。
144
144
 
145
- 手冊附錄 3 另附**各程式語言 URL_Encode 編碼表**(Java URLEncoder / RFC 3986 / PHP urlencode / PHP rawurlencode / C# UrlEncode / C# EscapeDataString 六欄對照)——跨語言實作前先查這張表。
145
+ `check_value` 的 URL encode **必須符合 Java `URLEncoder`**(手冊附錄 3):空白編成 `+`、`*` 不編碼、`~` 編成 `%7E`。PHP `urlencode`、Python `quote`、JS `encodeURIComponent` 都不同,值含空白、`*`、`~` 時簽章會錯。附錄 3 有六種語言的對照表。
146
146
 
147
147
  ## 4. API 端點
148
148
 
@@ -166,6 +166,42 @@ rsamsg → Base64 decode(URL-safe:- _) → 以「公鑰」分段解密
166
166
  > **CallBack 補發機制**:30 分鐘內每 5 分鐘補發一次,**超過 30 分鐘不再補發**。
167
167
  > ⚠️ **回傳網址不可帶 port**(如 `https://example.com:8080/x.php`),紅陽基於資安風險控管會擋。
168
168
  > 貨態通知為 **HTTP FORM POST key-value,非 JSON**。
169
+ > 收到 CallBack 並驗簽後回純文字 `success`(不含 HTML 或 JavaScript),紅陽收到即停止補發;`success` 不改變訂單狀態(§4.3.3,p.31)。
170
+
171
+ ### 請款 Capture(手冊 §4.5,p.41–43)
172
+
173
+ - 申請制;只能對 **21 天內**的交易請款。
174
+ - 外層 POST 欄位同交易:`web`、`send_time`、`rsamsg`、`check_value`(§3)。
175
+
176
+ | 位置 | 參數 | 長度 | 必填 | 說明 |
177
+ |---|---|---|---|---|
178
+ | head | `web` | 32 | ✅ | 特店代號 |
179
+ | body | `currency` | 4 | | `TWD`,空值預設 `TWD` |
180
+ | body | `mn` | 8 | ✅ | 請款金額,正整數;**分期付款與銀聯卡只能全額請款** |
181
+ | body | `td` | 50 | ✅ | 特店訂單編號 |
182
+ | body | `trade_no` | 19 | | 紅陽交易編號 |
183
+
184
+ 回應為明文 JSON:`code`(`00` 請求成功 / `99` 請求失敗)、`msg`。
185
+
186
+ ### 退款 Refund(手冊 §4.6,p.44–47)
187
+
188
+ - 申請制,且只接受事先登記白名單的 IP;只能對 **170 天內**的交易退款,逾期需另向紅陽申請。
189
+ - 外層 POST 欄位同交易。
190
+
191
+ | 位置 | 參數 | 長度 | 必填 | 說明 |
192
+ |---|---|---|---|---|
193
+ | head | `send_time` | 17 | ✅ | `fffssmmHHyyyyMMdd`,120 秒內有效 |
194
+ | head | `web` | 32 | ✅ | 特店代號 |
195
+ | body | `card_type` | 2 | ✅ | `01` 信用卡 / `02` 銀聯卡 / `03` Apple Pay、Google Pay / `10` 街口支付 |
196
+ | body | `currency` | 4 | | `TWD`,空值預設 `TWD` |
197
+ | body | `mn` | 8 | ✅ | 退款金額,正整數 |
198
+ | body | `refund_memo` | 100 | ✅ | 退款原因,不可有 `*'<>[]"` 等特殊字元 |
199
+ | body | `td` | 50 | ✅ | 特店訂單編號 |
200
+ | body | `trade_no` | 19 | | 紅陽交易編號 |
201
+
202
+ 回應為明文 JSON:`code`、`msg`,代碼見 §6「退款 API 的 `code`」。
203
+
204
+ > ⚠️ 請款的 `head` 只有 `web`,退款的 `head` 有 `send_time` 與 `web`(手冊範例亦同)。
169
205
 
170
206
  ## 5. 交易 (Cash) 請求參數
171
207
 
@@ -378,24 +414,32 @@ rsamsg → Base64 decode(URL-safe:- _) → 以「公鑰」分段解密
378
414
 
379
415
  聯絡:(02) 2502-6969
380
416
 
381
- ## 9. 待補
417
+ ## 9. 與官方 Claude Code Skill 的差異
418
+
419
+ 紅陽開發者專區提供「金流 AI 串接指南(Claude Code Skill)v1.1.0」(`sunpay-payment-skill-v1.1.0-v1.zip`,231 行),
420
+ 涵蓋付款導頁、回呼解簽、即時查詢、請款、超商取貨;**不含退款欄位、物流狀態通知、隨交易開立發票**。
382
421
 
383
- **金流側已完成**:端點(§4)、加解密(§3)、交易全欄位(§5)、代碼表(§6)。
422
+ | 項目 | 官方 skill | 手冊 v1.1.0 |
423
+ |---|---|---|
424
+ | `check_value` 的 URL encode | PHP `urlencode`(英數與 `-_.` 以外全編碼)| 附錄 3:須符合 Java `URLEncoder`(空白 `+`、`*` 不編碼、`~` 編為 `%7E`)|
425
+ | CallBack 補發 | 30 分鐘內重送 5 次 | 30 分鐘內每 5 分鐘補發一次(§4.3.3)|
384
426
 
385
- **金流側已完整**:端點(§4)、加解密(§3)、交易全欄位含五種支付方式的專屬參數(§5)、回應與代碼(§6)。
427
+ 兩者至少在 `*` 上不同(Java 不編碼、PHP 編為 `%2A`;附錄 3 對 `~` 也列出不同寫法),值含這些字元時算出的 `check_value` 不同。官方 skill 附的 `check_value` 自檢向量
428
+ (`0994ecc3…671d`)已用 `examples/sunpay-payment-example.py` 驗證相符。
386
429
 
387
- | 項目 | 優先 | 來源 | 備註 |
388
- |---|---|---|---|
389
- | 請款 / 退款 API 的請求欄位 | 中 | 金流手冊 §4.4–4.5 | 端點與 `refund_status` 已確認 |
390
- | 物流貨態 `StoreType` 代碼表 | 中 | — | ⚠️ **手冊未提供代碼對照**,僅說明是「物流狀態之代碼」,需洽紅陽索取 |
391
- | 統一錯誤碼表 | 中 | — | ⚠️ 手冊無獨立錯誤碼章節,僅有各 API 的 `pay_result`;已全數收錄於 §6 |
392
- | 對照紅陽官方 Claude Code Skill 的涵蓋範圍 | 高 | skill zip | 決定我們補到什麼程度 |
430
+ ## 10. 待補
431
+
432
+ | 項目 | 備註 |
433
+ |---|---|
434
+ | 物流貨態 `StoreType` 代碼表 | 手冊只說是「物流狀態之代碼」,未附對照,需洽紅陽索取 |
435
+ | 統一錯誤碼表 | 手冊無獨立錯誤碼章節,各 API 的 `pay_result`/`code` 已收錄於 §6 |
393
436
 
394
437
  電子發票側見 [../../taiwan-invoice/references/SUNPAY_API_REFERENCE.md](../../taiwan-invoice/references/SUNPAY_API_REFERENCE.md)。
395
438
 
396
- ## 10. 來源
439
+ ## 11. 來源
397
440
 
398
441
  - 開發者專區 — https://www.sunpay.com.tw/developers/
442
+ - 金流 AI 串接指南(Claude Code Skill)v1.1.0 — `https://storage.googleapis.com/joinchill-image/sunpay_techdoc/202607/sunpay-payment-skill-v1.1.0-v1.zip`
399
443
  - 教學手冊站 — https://doc.esafe.com.tw/
400
444
  - 操作手冊 — https://www.sunpay.com.tw/manual/
401
445
  - 金流串接頁 — https://www.sunpay.com.tw/金流串接/
package/dist/index.js CHANGED
@@ -16358,7 +16358,7 @@ function listCommand() {
16358
16358
  var import_chalk5 = __toESM(require_source());
16359
16359
 
16360
16360
  // src/version.ts
16361
- var VERSION = "1.5.5";
16361
+ var VERSION = "1.5.6";
16362
16362
 
16363
16363
  // src/commands/info.ts
16364
16364
  async function infoCommand() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taiwan-payment-skill",
3
- "version": "1.5.5",
3
+ "version": "1.5.6",
4
4
  "description": "AI-powered Taiwan Payment Gateway toolkit. Supports 14 providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay v4, TapPay, O'Pay, JKOPAY, SunPay and GoMyPay.",
5
5
  "keywords": [
6
6
  "taiwan",