taiwan-payment-skill 1.4.0 → 1.4.1

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/README.md CHANGED
@@ -109,7 +109,7 @@ taiwan-payment init --global # 全域安裝
109
109
 
110
110
  ## 14 個 AI 平台支援
111
111
 
112
- Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
112
+ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
113
113
 
114
114
  ## 相關套件
115
115
 
@@ -116,7 +116,7 @@ When modifying files:
116
116
  | Kiro | `.kiro` | full |
117
117
  | Codex | `.codex` | full |
118
118
  | Qoder | `.qoder` | full |
119
- | Roo Code | `.roo` | full |
119
+ | Cline | `.cline` | full |
120
120
  | Gemini | `.gemini` | full |
121
121
  | Trae | `.trae` | full |
122
122
  | OpenCode | `.opencode` | full |
@@ -187,3 +187,13 @@ jkopay,UP-001,取得用戶資料成功,Success,success,info,
187
187
  jkopay,UP-460,Access Token 過期,Access token expired,auth,error,以 refresh_token 換取新的 access_token
188
188
  jkopay,UP-999,用戶資料系統異常,System error,server,error,稍後重試
189
189
  jkopay,405,權限不足,Permission denied,auth,error,JOP Gateway 該 client_id 未取得此 API 權限 洽街口開放平台開通
190
+ jkopay,0001,街口幣發放成功,Success,success,info,
191
+ jkopay,2-GW-0997,服務維護中(Gateway),Service is under maintenance,server,error,街口幣發放閘道維護中 稍後以同一 exchangeId 重試
192
+ jkopay,2-GW-0201,驗簽失敗(Gateway),Signature verification failed,auth,error,街口幣發放的簽章與線上支付同規則 HMAC-SHA256 簽 payload 原文 注意 Header 為 Api-Key 與 Digest 首字大寫
193
+ jkopay,2-MT-9001,欄位檢核失敗,Validation failed,validation,error,檢查 clientId exchangeId amount jkosId 四個必填欄位
194
+ jkopay,2-MT-9002,發放對象不存在,Target user not found,validation,error,確認 jkosId 為有效的街口用戶 UUID
195
+ jkopay,2-MT-9003,發放金額需大於0,Amount must be greater than zero,validation,error,amount 必須大於 0
196
+ jkopay,2-MT-9004,驗證失敗,Authentication failed,auth,error,確認 Api-Key 正確且已開通街口幣發放權限
197
+ jkopay,2-MT-9006,exchangeId 請求不一致,Inconsistent request for exchangeId,validation,error,同一 exchangeId 帶了不同參數 屬實作錯誤非暫時性失敗 請修正參數而非重試
198
+ jkopay,2-MT-9005,街口幣發放內部錯誤,Internal service error,server,error,訂單卡在處理中可能已發幣成功 必須以「同一個」exchangeId 重送直到取得明確結果 換號會重複發幣
199
+ jkopay,2-MT-9999,街口幣發放非預期錯誤,Unspecified Error,server,error,同 2-MT-9005 必須以同一個 exchangeId 重送 不可換號
@@ -10,6 +10,6 @@ shopline,Shopline Payments,merchantId + apiKey HTTP Header,Header 認證 + HMAC-
10
10
  linepay,LINE Pay v4,Channel ID + Channel Secret,HMAC-SHA256 簽章 (X-LINE-Authorization-Nonce + Signature),https://sandbox-api-pay.line.me,https://api-pay.line.me,請至 LINE Pay Merchant Center 申請,請至 LINE Pay Merchant Center 申請,,application/json,LINE 生態 | 全球用戶 | 自動扣款 (Preapproved Pay) | 信用卡/帳戶餘額/POINT | 連加電支,large,RESTful JSON,public,https://developers-pay.line.me/zh/online-api-v4,2026-08-08
11
11
  tappay,TapPay,Partner Key + App Key + Merchant ID,Prime → pay-by-prime 兩段式,https://sandbox.tappaysdk.com,https://prod.tappayapis.com,請至 TapPay Portal 申請,請至 TapPay Portal 申請,請至 TapPay Portal 申請,application/json,PCI 隔離 | SDK 取得 Prime 後後端付款 | 信用卡/Apple Pay/Google Pay/LINE Pay/街口/全支付/全盈+PAY/悠遊付/一卡通/AFTEE/Virtual Account,medium,RESTful JSON,public,https://docs.tappaysdk.com/,2026-08-08
12
12
  opay,歐付寶 O'Pay,SHA256,URL Encode + SHA256 (同 ECPay CheckMacValue),https://payment-stage.opay.tw/Cashier/AioCheckOut/V5,https://payment.opay.tw/Cashier/AioCheckOut/V5,2000132,5294y06JbISpM5x9,v77hoKGq4kWxNNIS,application/x-www-form-urlencoded,專營電支機構 | 與 ECPay 同源架構 | 獨有 AccountLink 銀行快付/TopUpUsed 儲值消費/WeiXinpay 微信/TWQR | 延遲撥款 HoldTradeAMT | 購物金紅包折抵 | 金流+B2C/B2B/離線發票全公開 PDF,medium,Form POST,public,https://developers.opay.tw/download/document,2026-08-08
13
- jkopay,街口支付 JKOPAY,api-key Header + digest 簽章 (POS用Sign OAuth用sign),三套並存: 線上支付HMAC-SHA256簽payload原文 / POS SHA256簽排序JSON尾接MerchantKey須全小寫 / OAuth SHA256簽secret+jsonBody+天數,https://[HOST]/platform (測試付款域 test-onlinepay.jkopay.app),https://[HOST]/platform,請至街口申請,請至街口申請,,application/json,專營電支機構 | 官方公開文件站 | 授權扣款(定期)/線上支付/線下POS/inApp OAuth/街口幣發放 | Entry冪等同單回同網址 | payment_url長度>255 | QRCode僅20分鐘可展延 | 回傳invoice_vehicle可接發票 | 退款180天且用券訂單僅全額退 | 授權扣款限08:00-20:00且同auth_no不可併發 | TWQR 參與機構,large,RESTful JSON,public,https://open-doc.jkos.com/,2026-08-08
13
+ jkopay,街口支付 JKOPAY,api-key Header + digest 簽章 (POS用Sign OAuth用sign),三套並存: 線上支付HMAC-SHA256簽payload原文 / POS SHA256簽排序JSON尾接MerchantKey須全小寫 / OAuth SHA256簽secret+jsonBody+天數,https://[HOST]/platform (測試付款域 test-onlinepay.jkopay.app),https://[HOST]/platform,請至街口申請,請至街口申請,,application/json,專營電支機構 | 官方公開文件站 | 授權扣款(定期)/線上支付/線下POS/inApp OAuth/街口幣發放 | Entry冪等同單回同網址 | payment_url長度>255 | QRCode僅20分鐘可展延 | 回傳invoice_vehicle可接發票 | 退款180天且用券訂單僅全額退 | 授權扣款限08:00-20:00且同auth_no不可併發 | 折抵金額付款為負退款為正 | 街口幣發放需以同一exchangeId重試否則重複發幣 | 四組網域四套代碼空間 | TWQR 參與機構,large,RESTful JSON,public,https://open-doc.jkos.com/,2026-08-08
14
14
  sunpay,紅陽科技 SunPay,web + send_time + rsamsg + check_value,RSA分段加密(加密117byte/解密128byte)+Base64 與 SHA256簽章(ASCII排序後尾接SHA2密鑰),https://testtrade.sunpay.com.tw/v4/cash,https://trade.sunpay.com.tw/v4/cash,請至後台申請,RSA公鑰(PEM),SHA2密鑰,application/x-www-form-urlencoded,台灣老牌 | 金流+發票+超商代收+物流(超商便利送/宅配通) | 14家中唯一用RSA不可沿用他家加解密 | send_time格式fffssmmHHyyyyMMdd且120秒逾時 | pay_result值12在交易通知與查詢API意義不同 | 回傳網址不可帶port | CallBack僅補發30分鐘 | 物流限2萬元內 | WooCommerce/Magento2/OpenCart 官方模組 | 官方已出 Claude Code Skill(競品訊號),small,Form POST,public,https://www.sunpay.com.tw/developers/,2026-08-08
15
15
  gomypay,GoMyPay 台灣萬事達金流,待補,待補,待補,待補,請至後台申請,請至後台申請,,待補,第三方支付 | 信用卡/銀聯/WEBATM/虛擬帳號/超商條碼/定期扣款 | 行動支付手冊完整(台灣PAY/悠遊付/Apple Pay/Google Pay) | 微信線上線下 | 自營發票加值中心,small,Form POST,apply,https://n.gomypay.asia/MDocuments_downloads.aspx,2026-08-08
@@ -42,3 +42,5 @@ WooCommerce/Magento/OpenCart 官方模組,sunpay,MEDIUM,三大自架購物車皆
42
42
  不定期不定額授權,jkopay,HIGH,limited 模式授權後可在額度內隨時扣款 | 適合用量計費與儲值加值 | 額度上限由消費者在App自行設定商家不可控,固定金額訂閱請改用 regular 模式,按用量計費 | 儲值加值 | 變動金額扣款
43
43
  RSA加密金流,sunpay,MEDIUM,紅陽為本 skill 14 家中唯一使用 RSA 分段加密者 | 加密117byte解密128byte | check_value 為 ASCII 排序後尾接 SHA2 密鑰的 SHA256,團隊已熟悉 ECPay CheckMacValue 或 AES 家族且不想再導入 RSA,既有系統已用 RSA | 需要非對稱加密
44
44
  金流發票物流一家包辦,sunpay,MEDIUM,金流+電子發票+超商代收+物流(超商便利送/宅配通)同一家 | 支援隨交易自動開立發票 | 宅配通少數可經聚合商取得的路徑,已自行串接發票系統者請勿啟用隨交易開立以免重複開立,一站式整合 | 宅配通需求 | 減少廠商數量
45
+ 街口幣行銷發放,jkopay,HIGH,街口幣發放 API 可直接發幣給指定用戶做行銷 為聚合商完全無法提供的能力,需自行處理重試冪等 收到 internal error 必須以同一 exchangeId 重送否則重複發幣,街口幣 行銷發放 會員獎勵 積分
46
+ 街口實體店POS完整串接,jkopay,HIGH,POS 模組含付款 取消 退款 查詢四支與 33 個統一錯誤碼,簽章與線上支付不同須另寫;折抵金額正負與線上支付相反,POS 實體店 收銀機 條碼收款
@@ -35,3 +35,9 @@ RESTful 端點錯誤,404 Not Found | 405 Method Not Allowed,端點路徑錯誤 |
35
35
  街口 POS 折抵金額算錯,對帳金額與街口不符,POS 回傳的 RedeemAmount 與 StoreRedeemAmount 為負值 與線上支付 redeem_detail 的正值相反,POS 端對帳時折抵金額需取絕對值或直接相加(因其為負);實扣金額請用 DebitAmount,jkopay,medium
36
36
  街口 POS 斷線重送重複計費,同一筆交易出現兩筆成功紀錄,POS 端逾時重送時未檢查回應的 IsRep 欄位,IsRep=1 代表街口判定為重複交易 應視為同一筆而非新交易,jkopay,high
37
37
  街口代碼 301 意義判斷錯誤,依錯誤碼處理卻走錯分支,Platform API 的 301 是 Invalid auth_no 但 POS 的 StatusCode 301 是網路或系統異常 兩套代碼空間數字會相撞,依模組分開維護代碼對照表 勿共用同一份 mapping,jkopay,high
38
+ 街口幣重複發放,同一筆行銷活動發了兩次街口幣,收到 2-MT-9005 或 2-MT-9999 後換了新的 exchangeId 重送 街口視為新交易,必須用同一個 exchangeId 重送;帶相同 exchangeId 為冪等會回原訂單結果,jkopay,high
39
+ 街口折抵金額正負號反了,對帳金額差兩倍折抵金額,同名欄位在不同情境正負相反 付款與付款查詢為負值 退款與退款查詢為正值 線上支付的 redeem_detail 則一律為正值,在解析層依來源正規化正負號 勿在計算層才處理,jkopay,high
40
+ 街口 POS 查詢回 916 查無此訂單,剛送出的交易查不到,付款或退款送出後 15 秒內查詢可能因交易仍進行中而回 916,等待 15 秒後再查;另已送出 Cancel 的交易不可使用查詢 API,jkopay,medium
41
+ 街口 POS 退款單號用錯欄位,退款失敗或退到錯的訂單,POS 退款的 MerchantTradeNo 是退款流水號不是原付款流水號 原交易須用 TradeNo 指定,MerchantTradeNo 帶新的唯一退款單號 TradeNo 帶原街口端交易序號,jkopay,high
42
+ 街口線上支付退款單號重送無效,重送退款請求沒有反應或被拒,refund_order_id 一筆只能退一次 重送同號不會重試而是視為已使用,逾時後改用 Inquiry API 查詢結果 勿換號重送否則會變成第二筆退款,jkopay,high
43
+ 街口幣回應欄位解析失敗,取不到 Result 或 ResultObject,街口幣發放的回應欄位為 PascalCase(Result/Message/ResultObject) 與線上支付的小寫(result/message/result_object)不同,依模組分別定義回應模型 勿共用同一個 DTO,jkopay,medium
@@ -3,7 +3,7 @@
3
3
  > 官方開放文件: https://open-doc.jkos.com/
4
4
  > 公司: 街口電子支付股份有限公司(專營電子支付機構)
5
5
  > Captured: 2026-08-08 · doc_access: **public**(文件站免登入)
6
- > Status: **五大模組已擷取四個** —— 線上支付(§5)、授權扣款(§6)、線下 POS(§8)、inApp OAuth(§9);街口幣發放待補
6
+ > Status: **五大模組全數擷取完成** —— 線上支付(§5)、授權扣款(§6)、線下 POS(§8)、inApp OAuth(§9)、街口幣發放(§11)
7
7
  > 擷取方式: 文件站為 SPA,WebFetch 深層連結回 404,本次以瀏覽器逐頁取得
8
8
 
9
9
  ## 0. 為什麼收錄
@@ -268,13 +268,35 @@ Platform APIs 統一回應格式(**欄位皆小寫**,`result` 為**字串**
268
268
 
269
269
  查詢回傳的 `transactions[]` 結構與 `result_url` 的 `transaction` 相同,另含 `refund_history[]`。
270
270
 
271
- ### 5.7 其他端點
271
+ ### 5.7 訂單退款 `POST /platform/refund`
272
272
 
273
- | 端點 | 用途 |
274
- |---|---|
275
- | `POST /platform/refund` | 訂單退款 |
276
- | `GET /platform/inquiry` | 訂單查詢,參數 `platform_order_ids`(**複數,逗號分隔可批次查**)|
277
- | 交易撥款檔 R File | 對帳用的撥款檔(Reimburse File)|
273
+ 支援全額與**多次部分退款**,累積退款金額不可超過訂單實際消費金額。
274
+
275
+ | 參數 | 型態 | 長度 | 必填 | 說明 |
276
+ |---|---|---|---|---|
277
+ | `platform_order_id` | string | 60 | ✅ | 原交易序號。街口會比對退款單號與訂單是否對應 |
278
+ | `refund_order_id` | string | 60 | ✅ | **電商端退款單號,須唯一。一筆退款單號只能退一次;要再退必須換號** |
279
+ | `refund_amount` | decimal | 20,0 | ✅ | 退款金額 |
280
+
281
+ Response `result_object`:`refund_tradeNo`、`debit_amount`、`redeem_amount`、`redeem_detail`(三種折抵)、`refund_time`。
282
+
283
+ > ⚠️ `refund_order_id` 的一次性語意容易誤用:**重送同一個退款單號不會「重試」,而是被視為已用過**。網路逾時後要確認結果請改用 Inquiry 查,不要換號重送——換號會變成第二筆退款。
284
+
285
+ ### 5.8 訂單查詢 `GET /platform/inquiry`
286
+
287
+ ```
288
+ GET https://[Host]/platform/inquiry?platform_order_ids={id1},{id2}
289
+ ```
290
+
291
+ | 參數 | 型態 | 長度 | 必填 | 說明 |
292
+ |---|---|---|---|---|
293
+ | `platform_order_ids` | string[] | 60 | ✅ | 逗號分隔,**一次最多查 20 筆** |
294
+
295
+ 回傳 `transactions[]`,每筆含付款資訊與 `refund_history[]`(`refund_order_id`、`refund_tradeNo`、`amount`、`debit_amount`、`redeem_amount`、`time`)。
296
+
297
+ > 官方範例中第二筆退款紀錄沒有 `refund_order_id`——舊資料可能缺欄,解析時別假設必存在。
298
+
299
+ 另有**交易撥款檔 R File**(Reimburse File)供對帳,欄位格式待補。
278
300
 
279
301
  ## 6. 授權扣款 Authorized Payment — 完整規格
280
302
 
@@ -475,6 +497,57 @@ Response 的 `result_object` 與 OnlinePay 的 `result_url` 同構(`tradeNo`
475
497
  > ⚠️ **折抵金額是負值**,跟線上支付的 `redeem_detail`(正值)相反。對帳時直接相加會算錯。
476
498
  > ⚠️ `IsRep=1` 代表街口判定為重複交易——POS 端斷線重送時必須看這個欄位,否則會誤認為兩筆成功交易。
477
499
 
500
+ ### 8.1 取消 `POST /{系統方名稱}/Cancel`
501
+
502
+ POS 送出付款後**與街口連線異常或逾時**時使用,取消該筆付款。
503
+
504
+ 欄位與付款相同,但**下列五個必須與原 Payment 請求完全一致**:`GatewayTradeNo`、`MerchantTradeNo`、`CardToken`、`TradeAmount`、`UnRedeem`。
505
+
506
+ Response 只回 `MerchantID`、`StoreID`、`GatewayTradeNo`、`MerchantTradeNo`、`PosID`、`TradeAmount`、`StatusCode`、`StatusDesc`、`ActionCode`。
507
+
508
+ ### 8.2 退款 `POST /{系統方名稱}/Refund`
509
+
510
+ ⚠️ **`MerchantTradeNo` 在這裡是「退款流水號」不是原付款流水號**,且須唯一;原交易改用 `TradeNo`(街口端交易序號)指定。
511
+
512
+ | 參數 | 說明 |
513
+ |---|---|
514
+ | `TradeNo` | String(25),**原街口端交易序號** |
515
+ | `MerchantTradeNo` | String(60),**退款流水號**,需唯一 |
516
+ | `TradeAmount` | 退款金額 |
517
+
518
+ Response 另含 `RefundTradeNo`、`RefundTradeTime`、`IsRep`、`PaymentType`、折抵三欄。
519
+
520
+ ### 8.3 查詢 `POST /{系統方名稱}/Inquiry`
521
+
522
+ 以 `InquiryType` 區分:`P` 查付款、`R` 查退款。`MerchantTradeNo` 依查詢類型帶付款或退款流水號。
523
+
524
+ **`OrderStatus` 兩種查詢的取值完全不同**:
525
+
526
+ | InquiryType | OrderStatus |
527
+ |---|---|
528
+ | `P` 付款查詢 | `1` 付款成功 / `2` 付款失敗 / `4` 全額退款成功 / `7` 部分退款成功 |
529
+ | `R` 退款查詢 | `2` 退款失敗 / `5` 退款成功 |
530
+
531
+ > ⚠️ **`2` 在付款查詢是「付款失敗」,在退款查詢是「退款失敗」**——語意雖相近但代碼集不同,不可共用 mapping。
532
+ > ⚠️ **交易送出後 15 秒內查詢可能回 `916` 查無此訂單**(交易仍在進行中)。POS 端逾時後不要立刻查,要等一下再查,否則會誤判為交易不存在。
533
+ > ⚠️ **已送出取消(Cancel)的交易請勿使用查詢 API**(官方明訂)。
534
+ > `StatusCode` 非 `000` 時,大部分欄位不會回傳——解析前先判斷 `StatusCode`。
535
+
536
+ ### 8.4 ⚠️ 折抵金額的正負號在 POS 內部就不一致
537
+
538
+ 同樣叫 `RedeemAmount` / `StoreRedeemAmount`,正負相反:
539
+
540
+ | 情境 | 正負 | 官方範例 |
541
+ |---|---|---|
542
+ | 付款(Payment)| **負值** | `RedeemAmount: -3` |
543
+ | 付款查詢(Inquiry `P`)| **負值** | `RedeemAmount: -2`, `StoreRedeemAmount: -1` |
544
+ | 退款(Refund)| **正值** | `RedeemAmount: 2`, `StoreRedeemAmount: 1` |
545
+ | 退款查詢(Inquiry `R`)| **正值** | `RedeemAmount: 2`, `StoreRedeemAmount: 1` |
546
+
547
+ 規則是「付款相關為負、退款相關為正」。再加上**線上支付(§5)的 `redeem_detail` 一律為正值**,同一家廠商三種正負慣例並存。
548
+
549
+ > 對帳程式若用同一個函式處理折抵金額,跨模組時金額會反號。建議在解析層就依來源正規化,不要在計算層才處理。
550
+
478
551
  ## 9. inApp 第三方服務 — OAuth / JOP Gateway
479
552
 
480
553
  給 ISV 業者取得街口使用者授權資料用,**網域與支付 API 完全不同**:
@@ -567,21 +640,90 @@ OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-
567
640
 
568
641
  > ⚠️ **`906` 條碼已失效與 `927` 條碼錯誤是 POS 最常見的兩個**——街口付款條碼有時效,收銀台掃碼到送出 API 之間不能拖太久。
569
642
 
570
- ## 11. 仍待補
643
+ ## 11. 街口幣發放 Issue JKOS Coins
644
+
645
+ 給外部平台發放街口幣做行銷用。**這是聚合商完全給不了的能力**(見 §2)。
646
+
647
+ | 環境 | Domain |
648
+ |---|---|
649
+ | UAT | `uat-marketing-ext.jkopay.app` |
650
+ | 正式 | `marketing-ext.jkopay.com` |
651
+
652
+ `POST https://{baseURL}/jkocoin/exchange`
653
+
654
+ ### Header
655
+
656
+ | Header | 說明 |
657
+ |---|---|
658
+ | `Content-Type` | `application/json` |
659
+ | `Api-Key` | 街口提供的 API Key |
660
+ | `Digest` | HMAC-SHA256 簽章 |
661
+
662
+ > ⚠️ **Header 名稱是首字大寫的 `Api-Key` / `Digest`**,線上支付則是全小寫 `api-key` / `digest`。HTTP header 雖不分大小寫,但若你的框架或簽章工具做字串比對,這裡會踩到。
663
+
664
+ 簽章規則**與線上支付相同**(HMAC-SHA256 簽 payload 原文),連官方範例用的測試 Secret Key 都是同一組。所以街口全部合計仍是 §7 的**三套**簽章,不是四套。
665
+
666
+ ### Request Body
667
+
668
+ | 參數 | 型態 | 長度 | 必填 | 說明 |
669
+ |---|---|---|---|---|
670
+ | `clientId` | string | 100 | ✅ | 呼叫端識別碼(街口提供)|
671
+ | `exchangeId` | string | 64 | ✅ | **交易唯一識別碼,需唯一不可重複** |
672
+ | `amount` | decimal | 20,0 | ✅ | 發放金額,**必須 > 0** |
673
+ | `jkosId` | string | 64 | ✅ | 發放對象 UUID |
674
+
675
+ ### Response — ⚠️ 欄位是 PascalCase
676
+
677
+ ```json
678
+ { "Result": "0001", "Message": null, "ResultObject": { "jkosId": "...", "issueTime": "...", "amount": 20 } }
679
+ ```
680
+
681
+ > ⚠️ **`Result` / `Message` / `ResultObject` 首字大寫**,而線上支付與授權扣款是全小寫 `result` / `message` / `result_object`。街口文件自己也特別標註過這個大小寫差異。
682
+
683
+ `issueTime` 為 **ISO-8601**(`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`),與其他模組的 `yyyy-MM-dd HH:mm:ss` 不同。
684
+
685
+ ### 回應碼 — 第四套代碼空間
686
+
687
+ | Result | 說明 |
688
+ |---|---|
689
+ | `0001` | 成功 |
690
+ | `2-GW-0997` | 服務維護中(Gateway)|
691
+ | `2-GW-0201` | 驗簽失敗(Gateway)|
692
+ | `2-MT-9001` | 欄位檢核失敗 |
693
+ | `2-MT-9002` | 發放對象不存在 |
694
+ | `2-MT-9003` | 發放金額需大於 0 |
695
+ | `2-MT-9004` | 驗證失敗 |
696
+ | `2-MT-9006` | **`exchangeId` 請求不一致** |
697
+ | `2-MT-9005` | Internal service error ← **必須重試** |
698
+ | `2-MT-9999` | 非預期的錯誤 ← **必須重試** |
699
+
700
+ ### ⚠️ 重試語意攸關金錢,不可自行改寫
701
+
702
+ 收到 `2-MT-9005` 或 `2-MT-9999` 時,**必須用同一個 `exchangeId` 重送**直到取得明確結果。
703
+
704
+ 官方說明:這兩種錯誤代表訂單卡在「處理中」,**背後可能已經發幣成功也可能失敗**。用同一 `exchangeId` 重送,街口才會確認狀態並更新為成功或失敗。
705
+
706
+ > ⚠️ **換一個 `exchangeId` 重送 = 新的一筆交易**,不但拿不到原交易結果,還有**重複發幣**的風險。
707
+ > 相對地,帶相同 `exchangeId` 正常呼叫是**冪等**的,會回同一筆訂單結果——所以重送是安全的。
708
+ > `2-MT-9006`(exchangeId 請求不一致)代表你用同一個 `exchangeId` 但帶了不同的參數,這是實作錯誤而非可重試的暫時性失敗。
709
+
710
+ ### 查詢 API 尚未提供
711
+
712
+ 官方標註「目前尚未提供,但建議先將 GET parameters 處理好未來方便介接」,並已給出簽章格式(`clientId=...,exchangeId=...`)。**目前只能靠重送同一 `exchangeId` 來確認狀態。**
713
+
714
+ ## 12. 仍待補
715
+
716
+ 五大模組的 API 皆已擷取,剩餘為週邊項目:
571
717
 
572
718
  | 待補項目 | 優先 | 備註 |
573
719
  |---|---|---|
574
- | OnlinePay 退款 / 查詢 API 的 request 逐欄 | 中 | Response Code 已完整,request 欄位待擷取 |
575
- | POS 取消 / 退款 / 查詢 API 的欄位 | 中 | 付款 API 與統一錯誤碼已完成 |
576
- | 街口幣發放 API | 低 | 五大模組中唯一未觸及 |
577
- | R File(店家撥款檔)欄位格式 | 低 | OnlinePay 與 POS 皆有 |
720
+ | R File(店家撥款檔)欄位格式 | 中 | 線上支付與 POS 皆有此檔,對帳需要 |
578
721
  | Web SDK | 低 | 版本多(v2.0.2–v2.0.8 + Next),需先確認採用版本 |
579
-
580
- 已完成:**線上支付**(§5)、**授權扣款**(§6)、**線下 POS**(§8)、**inApp OAuth**(§9)、**統一錯誤碼表**(§10)。
722
+ | 街口幣查詢 API | — | **官方尚未提供**,僅先公布簽章格式 |
581
723
 
582
724
  `data/payment-methods.csv` 中 NewebPay/ezPay 的 `JKOPAY?` 推測碼**仍未驗證**——街口官方文件只描述直連,不涉及各聚合商如何命名自家代碼,需由各聚合商文件確認。
583
725
 
584
- ## 12. 來源
726
+ ## 13. 來源
585
727
 
586
728
  - 街口開放文件 — https://open-doc.jkos.com/
587
729
  - 線上支付 OnlinePay — https://open-doc.jkos.com/?docs=線上支付onlinepay
@@ -1,11 +1,12 @@
1
1
  {
2
- "platform": "roocode",
3
- "displayName": "Roo Code",
2
+ "platform": "cline",
3
+ "displayName": "Cline",
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
- "root": ".roo",
7
- "skillPath": "commands/taiwan-payment",
8
- "filename": "SKILL.md"
6
+ "root": ".cline",
7
+ "skillPath": "skills/taiwan-payment",
8
+ "filename": "SKILL.md",
9
+ "globalRoot": "~/.cline"
9
10
  },
10
11
  "scriptPath": "commands/taiwan-payment/scripts",
11
12
  "frontmatter": {
@@ -4,7 +4,7 @@
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
6
  "root": ".github",
7
- "skillPath": "prompts/taiwan-payment",
7
+ "skillPath": "skills/taiwan-payment",
8
8
  "filename": "SKILL.md"
9
9
  },
10
10
  "scriptPath": "prompts/taiwan-payment/scripts",
@@ -4,7 +4,7 @@
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
6
  "root": ".kiro",
7
- "skillPath": "steering/taiwan-payment",
7
+ "skillPath": "skills/taiwan-payment",
8
8
  "filename": "SKILL.md"
9
9
  },
10
10
  "scriptPath": "steering/taiwan-payment/scripts",
package/dist/index.js CHANGED
@@ -15824,7 +15824,7 @@ var AI_TYPES = [
15824
15824
  "kiro",
15825
15825
  "codex",
15826
15826
  "qoder",
15827
- "roocode",
15827
+ "cline",
15828
15828
  "gemini",
15829
15829
  "trae",
15830
15830
  "opencode",
@@ -15848,7 +15848,7 @@ var AI_TO_PLATFORM = {
15848
15848
  kiro: "kiro",
15849
15849
  codex: "codex",
15850
15850
  qoder: "qoder",
15851
- roocode: "roocode",
15851
+ cline: "cline",
15852
15852
  gemini: "gemini",
15853
15853
  trae: "trae",
15854
15854
  opencode: "opencode",
@@ -15990,8 +15990,8 @@ function detectAIType(cwd = process.cwd()) {
15990
15990
  if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".qoder"))) {
15991
15991
  detected.push("qoder");
15992
15992
  }
15993
- if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".roo"))) {
15994
- detected.push("roocode");
15993
+ if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".cline"))) {
15994
+ detected.push("cline");
15995
15995
  }
15996
15996
  if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".gemini"))) {
15997
15997
  detected.push("gemini");
@@ -16027,15 +16027,15 @@ function getAITypeDescription(aiType) {
16027
16027
  case "antigravity":
16028
16028
  return "Antigravity (.agent/skills/)";
16029
16029
  case "copilot":
16030
- return "GitHub Copilot (.github/prompts/)";
16030
+ return "GitHub Copilot (.github/skills/)";
16031
16031
  case "kiro":
16032
- return "Kiro (.kiro/steering/)";
16032
+ return "Kiro (.kiro/skills/)";
16033
16033
  case "codex":
16034
16034
  return "Codex CLI (.codex/skills/)";
16035
16035
  case "qoder":
16036
- return "Qoder (.qoder/rules/)";
16037
- case "roocode":
16038
- return "Roo Code (.roo/commands/)";
16036
+ return "Qoder (.qoder/skills/)";
16037
+ case "cline":
16038
+ return "Cline (.cline/skills/)";
16039
16039
  case "gemini":
16040
16040
  return "Gemini CLI (.gemini/skills/)";
16041
16041
  case "trae":
@@ -16323,7 +16323,7 @@ var PLATFORMS = [
16323
16323
  { name: "kiro", folder: ".kiro", description: "Kiro (AWS)" },
16324
16324
  { name: "codex", folder: ".codex", description: "Codex CLI (OpenAI)" },
16325
16325
  { name: "qoder", folder: ".qoder", description: "Qodo (Qoder)" },
16326
- { name: "roocode", folder: ".roo", description: "Roo Code" },
16326
+ { name: "cline", folder: ".cline", description: "Cline" },
16327
16327
  { name: "gemini", folder: ".gemini", description: "Gemini CLI" },
16328
16328
  { name: "trae", folder: ".trae", description: "Trae (ByteDance)" },
16329
16329
  { name: "opencode", folder: ".opencode", description: "OpenCode" },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taiwan-payment-skill",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "AI-powered Taiwan Payment Gateway toolkit. Supports 10 providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay v4, and TapPay.",
5
5
  "keywords": [
6
6
  "taiwan",