taiwan-payment-skill 1.5.9 → 1.5.10

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.
@@ -120,7 +120,7 @@ When modifying files:
120
120
  | Antigravity | `.agent` | full |
121
121
  | Copilot | `.github` | full |
122
122
  | Kiro | `.kiro` | full |
123
- | Codex | `.codex` | full |
123
+ | Codex | `.agents` | full |
124
124
  | Qoder | `.qoder` | full |
125
125
  | Cline | `.cline` | full |
126
126
  | Gemini | `.gemini` | full |
@@ -11,7 +11,7 @@ ecpay,10200047,MerchantTradeNo 重複,Duplicate MerchantTradeNo,validation,error
11
11
  ecpay,10200050,TotalAmount 超出範圍(金額不符),TotalAmount out of range,validation,error,檢查 TotalAmount(出處:綠界官方 skill guides/20,developers.ecpay.com.tw 未列,以後台「交易狀態代碼查詢」為準)
12
12
  ecpay,10200058,信用卡授權失敗,Card authorization failed,payment,error,請消費者確認卡片資訊或更換信用卡(出處:綠界官方 skill guides/20,developers.ecpay.com.tw 未列,以後台「交易狀態代碼查詢」為準)
13
13
  ecpay,10200073,CheckMacValue 驗證失敗,CheckMacValue verify fail,auth,error,不分大小寫排序、PHP urlencode 後轉小寫並還原 ( ) ! *、金流 SHA256 / 物流 MD5;確認 HashKey/HashIV(出處:綠界官方 skill guides/20,developers.ecpay.com.tw 未列,以後台「交易狀態代碼查詢」為準)
14
- ecpay,10200095,訂單未成立,消費者未完成付款,Already paid,payment,warning,查詢 API 的 TradeStatus;不是已付款或已退款(/2890)
14
+ ecpay,10200095,訂單未成立,消費者未完成付款,Transaction not completed (customer did not finish payment),payment,warning,查詢 API 的 TradeStatus;不是已付款或已退款(/2890)
15
15
  ecpay,10200105,BNPL 金額未達最低,BNPL amount below minimum,validation,error,"TotalAmount 需 >= 3,000 元(出處:綠界官方 skill guides/20,developers.ecpay.com.tw 未列,以後台「交易狀態代碼查詢」為準)"
16
16
  ecpay,10200115,信用卡授權逾時,Card authorization timeout,payment,error,請消費者重新付款(出處:綠界官方 skill guides/20,developers.ecpay.com.tw 未列,以後台「交易狀態代碼查詢」為準)
17
17
  ecpay,10300006,超商繳費期限已過(國內物流中為物流訂單已過期),CVS payment expired,payment,error,重新建立訂單;同一代碼在物流服務含意不同(出處:綠界官方 skill guides/20,developers.ecpay.com.tw 未列,以後台「交易狀態代碼查詢」為準)
@@ -1,7 +1,7 @@
1
1
  operation,operation_zh,ecpay_endpoint,newebpay_endpoint,payuni_endpoint,smilepay_endpoint,pchomepay_endpoint,ezpay_endpoint,paynow_legacy_endpoint,paynow_modern_endpoint,opay_endpoint,jkopay_endpoint,sunpay_endpoint,method,required_fields,notes
2
2
  create_order,建立訂單,/Cashier/AioCheckOut/V5,/MPG/mpg_gateway,/api/upp,/api/SPPayment.asp,/v1/payment,/API/Twqr/SCreateTWQR(境內);跨境 /MPG/mpg_gateway,/service/etopm.aspx,/api/v1/payment-intent/create,/Cashier/AioCheckOut/V5,/platform/entry,/v4/cash,POST,"MerchantID,MerchantTradeNo,TotalAmount,TradeDesc,ItemName,ReturnURL",主要付款入口;PChomePay 另有 /v1/payment/atmva (ATM) 與 /v1/payment/barcode (CVS code) | 歐付寶 O'Pay 路徑與綠界相同僅換網域;街口 JKOPAY 為 /platform/entry 且同單號冪等;紅陽 SunPay 為 /v4/cash
3
- query_order,查詢訂單,/Cashier/QueryTradeInfo/V5,/API/QueryTradeInfo,/api/trade/query,/ezpos/mtmk_utf.asp,/v1/payment/{order_id},/API/Twqr/SGetTWQR(境內);跨境 /API/merchant_trade/query_trade_info,N/A,/api/v1/payment-intent/{id},/Cashier/QueryTradeInfo/V5,/platform/inquiry (GET;最多20筆),/v4/query/PaymentCheck,POST,"MerchantID,MerchantTradeNo,TimeStamp",查詢交易狀態;SmilePay 用 mtmk 端點 | 街口 JKOPAY 查詢為 GET 且一次最多 20 筆;紅陽 SunPay 查詢的 pay_result=12 意為查無訂單與交易通知不同義
4
- credit_action,信用卡請退款,/CreditDetail/DoAction,/API/CreditCard/Close,/api/trade/close,/api/SPPayment_Modify.asp,/v1/refund,N/A,N/A,/api/v1/payment-intent/{id}/refund,/CreditDetail/DoAction,/platform/refund,/v3/Service/CardCapture (請款) 與 /v3/Service/CardRefund (退款),POST,"MerchantID,TradeNo,Action,TotalAmount",請款/退款/取消;PayNow 現代版用 PaymentIntent refund | 街口 JKOPAY 退款單號一筆只能退一次;紅陽 SunPay 請款與退款仍在 /v3/ 與交易查詢的 /v4/ 不同
3
+ query_order,查詢訂單,/Cashier/QueryTradeInfo/V5,/API/QueryTradeInfo,/api/trade/query,N/A,/v1/payment/{order_id},/API/Twqr/SGetTWQR(境內);跨境 /API/merchant_trade/query_trade_info,N/A,/api/v1/payment-intent/{id},/Cashier/QueryTradeInfo/V5,/platform/inquiry (GET;最多20筆),/v4/query/PaymentCheck,POST,"MerchantID,MerchantTradeNo,TimeStamp",查詢交易狀態;SmilePay 無公開查詢 API,以付款結果通知與後台交易查詢為準 | 街口 JKOPAY 查詢為 GET 且一次最多 20 筆;紅陽 SunPay 查詢的 pay_result=12 意為查無訂單與交易通知不同義
4
+ credit_action,信用卡請退款,/CreditDetail/DoAction,/API/CreditCard/Close,/api/trade/close,N/A,/v1/refund,N/A,N/A,/api/v1/payment-intent/{id}/refund,/CreditDetail/DoAction,/platform/refund,/v3/Service/CardCapture (請款) 與 /v3/Service/CardRefund (退款),POST,"MerchantID,TradeNo,Action,TotalAmount",請款/退款/取消;SmilePay 的 SPPayment_Modify.asp 為非公開 API(客服回覆 2026-09-30);PayNow 現代版用 PaymentIntent refund | 街口 JKOPAY 退款單號一筆只能退一次;紅陽 SunPay 請款與退款仍在 /v3/ 與交易查詢的 /v4/ 不同
5
5
  query_credit,信用卡查詢,/CreditDetail/QueryTrade/V2,/API/QueryTradeInfo,/api/trade/query,N/A,/v1/refund/{refund_id},N/A,N/A,/api/v1/refund/{id},/CreditDetail/QueryTrade/V2,N/A,N/A,POST,"MerchantID,CreditRefundId",查詢信用卡交易
6
6
  periodic_create,定期定額建立,/Cashier/AioCheckOut/V5,/MPG/period,,N/A,N/A,,N/A,/api/v1/customer (saved card),/Cashier/AioCheckOut/V5,/platform/authpay/regular 或 /limited,N/A,POST,"PeriodAmount,PeriodType,Frequency,ExecTimes",設定週期付款;PayNow 現代版用 Customer + Card Token 機制 | 街口 JKOPAY 授權扣款分定期定額 regular 與不定期不定額 limited 兩種;歐付寶 O'Pay 同綠界定期定額
7
7
  periodic_query,定期定額查詢,/Cashier/QueryCreditCardPeriodInfo,/MPG/period/query,,N/A,N/A,,N/A,N/A,/Cashier/QueryCreditCardPeriodInfo,/platform/authpay/detail,N/A,POST,"MerchantID,MerchantTradeNo",查詢週期付款
@@ -26,7 +26,7 @@ icash,愛金卡,iCash,,,ICASH,,,,,iCashPay,,1,,2-3,percentage,PAYUNi 直送 ICAS
26
26
  ezpalipay,簡單付支付寶,Alipay,,EZPALIPAY,,,,,ALIPAY(跨境),,,1,,2-3,percentage,跨境支付
27
27
  ezpwechat,簡單付微信,WeChat Pay,,EZPWECHAT,,,,,WECHAT(跨境),,,1,,2-3,percentage,跨境支付
28
28
  pcpay_wallet,拍錢包,PChome Wallet,,,,,,PI,,,,1,,2-3,percentage,PChomePay 獨家;含 5% P 幣回饋
29
- cvs_cod,超商取貨付款,CVS COD,,CVSCOM,,,,COD,,,09 (需 lgs_flag=1),1,20000,1-3,fixed,NewebPay 用 CVSCOM (值: 1=取貨不付款 2=取貨付款 3=兩者);PChomePay 用 COD 對應 7-Eleven 取貨
29
+ cvs_cod,超商取貨付款,CVS COD,,CVSCOM,,,,COD,,,09 (需 lgs_flag=1),1,20000,1-3,fixed,NewebPay 用 CVSCOM (值: 1=取貨不付款 2=取貨付款 3=兩者);PChomePay 用 COD 對應 7-Eleven 取貨;SunPay 超商取貨付款不支援 OK(store_type 移除 3,紅陽客服 2026-09-29)
30
30
  weixinpay,微信支付,WeChat Pay (ECPay),WeiXin,EZPWECHAT,,WeiXinpay,,,WECHAT(跨境),,,1,,2-3,percentage,ECPay 直接 ChoosePayment=WeiXin;NewebPay 走 EZPWECHAT;O'Pay WeiXinpay 已驗證(MerchantTradeNo 限 32 位元、繳費期限 2 小時、無測試回應)
31
31
  digital_payment,電子支付/電子錢包 umbrella,Digital Payment Umbrella,DigitalPayment,,,,,,,,,1,,2-3,percentage,ECPay 專屬;子項目只有 Jkopay(街口)與 iPASS(一卡通 MONEY),可用 ChooseSubPayment 指定(/5679)
32
32
  jkopay,街口支付,JKO Pay,DigitalPayment,TWQR,JKoPay,,,,TWQR,,10,1,,2-3,percentage,同一街口服務跨家命名不同;ECPay 為 DigitalPayment + ChooseSubPayment=Jkopay;PAYUNi JKoPay 已驗證;NewebPay 無個別錢包代碼,以 TWQR=1 收款(NDNF-1.2.5)
@@ -11,5 +11,5 @@ linepay,LINE Pay v4,Channel ID + Channel Secret,HMAC-SHA256 簽章 (X-LINE-Autho
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
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
- 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,台灣老牌 | 金流+發票+超商代收+物流(超商取貨付款;官網物流頁另列全家大宗與C2C 7-11/全家/萊爾富) | 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
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,自行註冊 testmerchant.sunpay.com.tw(立即申請),RSA公鑰(PEM),SHA2密鑰,application/x-www-form-urlencoded,"台灣老牌 | 金流+發票+超商代收+物流(超商取貨付款,不支援OK;官方確認目前無物流API) | 14家中唯一用RSA不可沿用他家加解密 | send_time格式fffssmmHHyyyyMMdd且120秒逾時 | pay_result值12在交易通知與查詢API意義不同 | 回傳網址不可帶port | CallBack僅補發30分鐘 | 物流限2萬元內 | WooCommerce/Magento2/OpenCart 官方模組 | 官方已出 Claude Code Skill(競品訊號) | check_value 手冊v1.1.1起可不做URLEncode(做了也相容)",small,Form POST,public,https://www.sunpay.com.tw/developers/,2026-09-29
15
15
  gomypay,GoMyPay 台灣萬事達金流,需向 GoMyPay 申請,需向 GoMyPay 申請,需向 GoMyPay 申請,需向 GoMyPay 申請,需向 GoMyPay 申請,需向 GoMyPay 申請,,需向 GoMyPay 申請,第三方支付 | 信用卡(含分期)/銀聯/WEBATM/虛擬帳號/超商條碼/超商代碼/定期扣款 | 行動支付(台灣PAY/悠遊付/Apple Pay/Google Pay) | 微信線上線下 | 自營發票加值中心 | 官方購物車模組 WooCommerce/Magento2/OpenCart | 完整API規格未公開,small,Form POST,apply,https://n.gomypay.asia/MDocuments_downloads.aspx,2026-09-24
@@ -197,7 +197,6 @@ class SmilePayPaymentService:
197
197
  # API 端點
198
198
  PAYMENT_URL = 'https://ssl.smse.com.tw/api/SPPayment.asp' # 取號類
199
199
  CHECKOUT_URL = 'https://ssl.smse.com.tw/ezpos/mtmk_utf.asp' # 信用卡 / 銀聯
200
- MODIFY_URL = 'https://ssl.smse.com.tw/api/SPPayment_Modify.asp' # 訂單修改 / 退款
201
200
 
202
201
  def __init__(
203
202
  self,
@@ -89,6 +89,9 @@ def make_check_value(payload: Dict[str, Any], sha2_key: str) -> str:
89
89
 
90
90
  排序 → JSON → urlencode → 尾端直接串上 SHA2 密鑰 → SHA256。
91
91
 
92
+ 手冊 v1.1.1 起可不做 urlencode,做了也相容(紅陽客服回覆 2026-09-29);
93
+ 這裡維持 urlencode,才能用手冊範例值驗證。
94
+
92
95
  密鑰是接在字串尾端,不是 ECPay 那種
93
96
  `HashKey=...&參數&HashIV=...` 的前後包夾。
94
97
  值為 null 的參數不參與簽名(官方明註),本函式已於 build 階段排除。
@@ -5,6 +5,9 @@
5
5
  > 來源:速買配官方 WooCommerce 外掛兩個世代——
6
6
  > **1.1.23**(`smilepay-module-for-woocommerce`,單一外掛)與 **4.3.3**(各付款方式分檔:`smilepayatm.php`、`smilepaycredit.php`…,附 ReadMe 修訂日期 2023/03/31)。
7
7
  > 兩版不一致處逐項註明。速買配規格書需登入商家帳務後台,於左側選單「程式串接說明」取得。
8
+ > 另依**速買配客服回覆(2026-09-30)**補正 `Classif` 對照、銀聯檢核碼、測試卡與非公開 API 範圍;回覆中列出的三份 API 文件
9
+ > (背景取號 `pay_help_paydc_Background_api.ASP`、標準收款 `pay_help_paydc_api.ASP`、電子發票 `pay_help_paydc_einvoice_api.asp`)
10
+ > 位於 `ssl.smse.com.tw/pay_gr/`,未登入會導向商家登入頁。
8
11
 
9
12
  ---
10
13
 
@@ -61,7 +64,6 @@
61
64
  |------|------|
62
65
  | 訂單建立 (ATM/條碼/ibon/FamiPort) | `https://ssl.smse.com.tw/api/SPPayment.asp` |
63
66
  | 信用卡 / 銀聯 結帳頁 (GET / Form) | `https://ssl.smse.com.tw/ezpos/mtmk_utf.asp` |
64
- | 訂單修改 / 取消 (官方文件提供) | `https://ssl.smse.com.tw/api/SPPayment_Modify.asp` |
65
67
 
66
68
  ### 通知端點 (由商店實作,速買配回呼)
67
69
 
@@ -94,7 +96,15 @@ mid : 1111
94
96
 
95
97
  ### 測試卡號
96
98
 
97
- 信用卡 / 銀聯走 `mtmk_utf.asp` 模擬結帳頁,速買配會引導使用內部測試卡片,正式上線前向其客服索取最新測試卡號。
99
+ 試用帳號(`Dcvc=107`)發動信用卡交易時,`mtmk_utf.asp` 會導向測試刷卡頁 `ssl.smse.com.tw/PAY_TEST/smilepay_evpos_TestVisa_utf.ASP`,頁面上列出測試卡(SmilePay 客服回覆 2026-09-30;測試頁內容 2026-10-03 查核):
100
+
101
+ | 項目 | 值 |
102
+ |---|---|
103
+ | 卡號 | `1111-1111-1111-1234` |
104
+ | 到期日 | `01-18` |
105
+ | 末三碼 | `222` |
106
+
107
+ 其他卡號一律以授權失敗處理。
98
108
 
99
109
  ---
100
110
 
@@ -484,7 +494,7 @@ redirect_url = f"{base}?{urlencode(params)}"
484
494
 
485
495
  | 欄位 | 說明 |
486
496
  |------|------|
487
- | `Classif` | `A` = 授權;`O`/`T` = 完成 |
497
+ | `Classif` | `A` = 刷卡(完整對照見 [Classif 通知類型](#classif-通知類型)) |
488
498
  | `Response_id` | `1` = 成功;其他為失敗 |
489
499
  | `Smseid` | 速買配金流追蹤碼 |
490
500
  | `Amount` | 授權金額 |
@@ -509,6 +519,7 @@ else:
509
519
  **兩版外掛差異**
510
520
 
511
521
  - 結帳頁是瀏覽器轉址,兩版都把 `Verify_key` 放在 querystring,消費者可在網址列看到(4.3.3 `smilepaycredit.php` `credit_create_order`;1.1.23 `class-smilepay-payment-base.php`)。4.3.3 的銀聯轉址則不帶 `Verify_key`(`smilepayunion.php` `thankyou_page`)。
522
+ - `mtmk_utf.asp` 目前不需要 `Verify_key`,但日後版本將要求帶入,串接時應先預留(SmilePay 客服回覆 2026-09-30)。
512
523
  - 1.1.23 的 `credit_roturl` 會驗 `Mid_smilepay`;**4.3.3 的 `credit_roturl` 不驗**,只比對金額。自行實作時一律驗章。
513
524
  - 4.3.3 沒有分期;`Stage` 只見於 1.1.23。
514
525
  - `credit_roturl` 處理完即 `wp_redirect` 到訂單完成頁(兩版相同),代表它同時是消費者的返回網址。
@@ -591,7 +602,7 @@ Pay_zg = 11
591
602
 
592
603
  - 通知帶 `Classif=A` 與 **`Foreign=U`**,以此區分銀聯與一般信用卡
593
604
  - 失敗通知為 `Amount=0` 且 `Response_id=0`;成功為 `Response_id=1`
594
- - 失敗通知驗 `Mid_smilepay` 時,金額改用**訂單總額**而不是通知的 `0`(1.1.23 一律用通知的 `Amount`)
605
+ - 失敗通知驗 `Mid_smilepay` 時,金額用**訂單金額**而不是通知的 `0`:SmilePay 客服回覆 2026-09-30確認「無論交易成功或失敗,`Mid_smilepay` 均以訂單金額計算」。4.3.3 的做法正確,1.1.23 一律用通知的 `Amount` 是錯的
595
606
  - ReadMe:銀聯非即時回傳,約 5~20 分鐘後才會收到結果
596
607
 
597
608
  ---
@@ -623,19 +634,28 @@ SmilePay 在消費者完成付款 (取號類) 或刷卡 (信用卡 / 銀聯) 後
623
634
 
624
635
  ### Classif 通知類型
625
636
 
626
- | 值 | 說明 |
637
+ 官方對照(SmilePay 客服回覆 2026-09-30):
638
+
639
+ | 值 | 交易方式 |
627
640
  |----|------|
628
- | `A` | 信用卡授權;帶 `Foreign=U` 時為銀聯 |
629
- | `B` | ATM 虛擬帳號入帳 |
630
- | `C` | 超商條碼繳費 |
631
- | `E` | 7-11 ibon 代碼繳費 |
632
- | `F` | 全家 FamiPort 代碼繳費 |
633
- | `T` | 超商取貨付款(C2C) |
634
- | `V` | 超商取貨付款(B2C) |
635
- | `O` | 黑貓取貨付款 |
636
- | `D` | 4.3.3 列為 `smilepaycn`,未對應任何付款模組 |
637
-
638
- > 來源:4.3.3 `smilepay_respond.php` `smilepay_respond` 依 `Classif` 分派付款模組。
641
+ | `A` | 刷卡(4.3.3 外掛以 `Foreign=U` 區分銀聯) |
642
+ | `B` | 虛擬帳號 |
643
+ | `C` | 超商代收 |
644
+ | `D` | CVS 代碼繳費 |
645
+ | `E` | 7-11 ibon |
646
+ | `F` | FamiPort |
647
+ | `L` | LifeET |
648
+ | `O` | 黑貓貨到收現 |
649
+ | `P` | 黑貓宅配 |
650
+ | `Q` | 黑貓逆物流 |
651
+ | `T` | C2C 取貨付款 |
652
+ | `U` | C2C 純取貨 |
653
+ | `V` | B2C 取貨付款 |
654
+ | `W` | B2C 純取貨 |
655
+ | `R` | C2B 客付 |
656
+ | `S` | C2B 場付 |
657
+
658
+ > 4.3.3 外掛(`smilepay_respond.php` `smilepay_respond`)只處理 `A`/`B`/`C`/`D`/`E`/`F`/`T`/`V`/`O`,其中 `D` 未對應任何付款模組。
639
659
  > 1.1.23 對 `T`、`O` 直接改為 completed,其餘改為 processing;4.3.3 對 `T` 改為 completed,其餘 processing。
640
660
 
641
661
  ### 商店回應格式
@@ -722,42 +742,8 @@ def verify_callback(mid, amount, smseid, mid_smilepay_received) -> bool:
722
742
 
723
743
  ## 訂單查詢與退款
724
744
 
725
- ### 訂單修改 / 退款
726
-
727
- SmilePay 提供 `SPPayment_Modify.asp` 端點 (官方規格書) 用於:
728
-
729
- - 取消尚未授權的信用卡訂單
730
- - 信用卡退款 / 退刷
731
- - 修改 ATM 期限 / 金額
732
-
733
- ```
734
- POST https://ssl.smse.com.tw/api/SPPayment_Modify.asp
735
- Content-Type: application/x-www-form-urlencoded
736
- ```
737
-
738
- ### 通用必填
739
-
740
- | 欄位 | 說明 |
741
- |------|------|
742
- | `Dcvc` / `Rvg2c` / `Verify_key` | 帳號驗證 |
743
- | `Smseid` | 速買配金流追蹤碼 (對應 `SmilePayNO`) |
744
- | `Modify_type` | 動作代碼 (依官方規格設定) |
745
- | `Amount` | 退款 / 修改後金額 |
746
-
747
- > WooCommerce 模組未直接整合此 API,建議參考速買配最新版規格書 (`SmilePay_API_v*.pdf`) 取得完整 `Modify_type` 對照表。
748
-
749
- ### 訂單查詢
750
-
751
- 實務上 SmilePay 的後續通知為主要狀態來源;商家如需主動查詢 (對帳):
752
-
753
- - 透過商店後台「交易查詢」匯出
754
- - 或使用速買配提供的對帳 API (需另行開通)
755
-
756
- ### 退款限制 (一般慣例)
757
-
758
- - 信用卡:請款後 6 個月內 (依發卡銀行)
759
- - 部分退款:信用卡支援;ATM / 超商需走「退匯款」程序
760
- - 取號類訂單未付款者:可由商家直接標記為作廢,無需通知 SmilePay
745
+ - `SPPayment_Modify.asp` **不是對外公開的 API**,速買配不提供其規格(SmilePay 客服回覆 2026-09-30)。外掛兩版都未使用。
746
+ - 主動查詢交易請用商家後台「交易查詢」;交易狀態以付款結果通知為準。
761
747
 
762
748
  ---
763
749
 
@@ -916,6 +902,6 @@ def big5_to_utf8(text: str | bytes) -> str:
916
902
 
917
903
  - **官方網站**:https://www.smilepay.net/
918
904
  - **金流系統**:https://www.smse.com.tw/
919
- - **API 規格書**:商家帳務後台左側選單「程式串接說明」(需登入)
905
+ - **API 規格書**:商家帳務後台左側選單「程式串接說明」(需登入);客服回覆列出的公開版位於 `ssl.smse.com.tw/pay_gr/pay_help_paydc_Background_api.ASP`、`pay_help_paydc_api.ASP`、`pay_help_paydc_einvoice_api.asp`,未登入會導向登入頁
920
906
  - **客服**:+886-37-376006、service@smilepay.net(訊航科技,外掛 4.3.3 ReadMe)
921
907
 
@@ -42,7 +42,7 @@
42
42
  | 官網物流服務頁 https://www.sunpay.com.tw/logistics | 超商大宗貨運(全家大宗)、超商物流(7-11、全家、萊爾富店到店) |
43
43
  | 教學手冊站 https://doc.esafe.com.tw/ | 超商便利送、宅配通 |
44
44
 
45
- 金流 API 只提供**超商取貨付款**(`card_type=09`,§5),沒有宅配或宅配通的 API 規格。
45
+ 金流 API 只提供**超商取貨付款**(`card_type=09`,§5)。紅陽確認**目前不支援物流 API 串接**(紅陽客服回覆 2026-09-29),官網列的物流服務需透過後台使用。
46
46
 
47
47
  ### 電子發票
48
48
 
@@ -74,12 +74,14 @@
74
74
 
75
75
  ### 測試環境申請
76
76
 
77
- | 用途 | 入口 |
78
- |---|---|
79
- | 金流測試環境 | https://testmerchant.sunpay.com.tw/#/formTabs |
80
- | 電子發票測試帳號 | https://testinv.sunpay.com.tw/sign-up |
77
+ 測試帳號自行註冊即可使用(紅陽客服回覆 2026-09-29):
78
+
79
+ | 用途 | 入口 | 申請方式 |
80
+ |---|---|---|
81
+ | 金流測試環境 | https://testmerchant.sunpay.com.tw/#/login | 點選下方「立即申請」 |
82
+ | 電子發票測試帳號 | https://testinv.sunpay.com.tw/ | 點選右上角「帳號申請」 |
81
83
 
82
- 手冊 v1.1.1(2026-08-19)相對 v1.1.0 的異動:`store_type` 移除 `3`(OK);§4.2.3 簽名 Step 2 改寫(見 §3.2);刪除附錄 3(各語言 URL encode 對照表)。
84
+ 手冊 v1.1.1(2026-08-19)相對 v1.1.0 的異動:`store_type` 移除 `3`(OK,超商取貨付款不再支援 OK 超商);§4.2.3 簽名 Step 2 改寫(見 §3.2);刪除附錄 3(各語言 URL encode 對照表)。
83
85
 
84
86
  | 其他文件 | 取得 |
85
87
  |---|---|
@@ -136,22 +138,24 @@ rsamsg → Base64 decode(URL-safe:- _) → 以「公鑰」分段解密
136
138
 
137
139
  ```
138
140
  1. head 與 body(含內容)做 ASCII 升序排序
139
- 2. 整份 JSON 做 URLEncode,尾端直接串上 SHA2 密鑰
141
+ 2. 整份 JSON 字串(可先 URLEncode,見下方),尾端直接串上 SHA2 密鑰
140
142
  3. SHA256 → check_value
141
143
  ```
142
144
 
145
+ **URLEncode 兩種皆可**(紅陽客服回覆 2026-09-29):手冊 v1.1.1 優化了簽名步驟,可以不做 URLEncode;做了也相容。
146
+ 建議與 `rsamsg` 的加密明文使用**同一個字串**,避免兩邊編碼不一致。
147
+
143
148
  > ⚠️ **`null` 值的參數不參與簽名**(官方明註)。
144
149
  > ⚠️ **ASCII 排序是強制的**,手冊在兩處重複警告「請務必將 head 與 body 參數進行 ASCII 排序,以免加密失敗」。
145
- > ⚠️ SHA2 密鑰是**直接串接在 URLEncode 後字串的尾端**,不是 ECPay 那種 `HashKey=…&…&HashIV=…` 前後包夾。
150
+ > ⚠️ SHA2 密鑰是**直接串接在(URLEncode 後的)字串尾端**,不是 ECPay 那種 `HashKey=…&…&HashIV=…` 前後包夾。
146
151
 
147
- > ⚠️ **手冊 v1.1.1 的 Step 2 文字與範例矛盾**:文字改成「JSON 字串化後直接串上 SHA2 密鑰」(不做 URLEncode),
148
- > 但同頁範例的 `check_value`(`3df3acb3…cad26`)只有**先 URLEncode** 才算得出來;不做 URLEncode 會得到 `5ec973f1…e6ae`。
149
- > 官方範例程式(`sunpayWeb.php` 的 `getCheck_value()`、JAVA `Payment` 的 `ShaUtil.encodeSHA256(URLEncoder.encode(...) + SHA256)`)
150
- > 與官方 skill v1.1.1 也都是先 URLEncode。以上述三者為準。
152
+ > 手冊 v1.1.1 同頁範例的 `check_value`(`3df3acb3…cad26`)是先 URLEncode 的結果;不做 URLEncode 會得到 `5ec973f1…e6ae`。
153
+ > 官方範例程式(`sunpayWeb.php` 的 `getCheck_value()`、JAVA `Payment`)與官方 skill v1.1.1 都先 URLEncode。
154
+ > 本 skill 範例採 URLEncode 版本,可直接用官方範例值驗證。
151
155
 
152
156
  **URL encode 規則**:手冊 v1.1.0 附錄 3 要求符合 Java `URLEncoder`(空白 `+`、`*` 不編碼、`~` 編為 `%7E`),v1.1.1 已刪除附錄 3。
153
157
  官方 PHP 範例用 `urlencode`(`*` 編為 `%2A`),JAVA 範例用 `URLEncoder`;兩者都把**同一個編碼後字串**同時拿去做 RSA 加密與 `check_value`。
154
- 所以關鍵是 `rsamsg` 的明文與 `check_value` 用同一個字串;本 skill 範例採 Java `URLEncoder` 規則。
158
+ 若做 URLEncode,關鍵是 `rsamsg` 的明文與 `check_value` 用同一個字串;本 skill 範例採 Java `URLEncoder` 規則。
155
159
  Python `quote`(空白編為 `%20`)與 JS `encodeURIComponent` 不屬於官方範例的任一種,不要直接用。
156
160
 
157
161
  ## 4. API 端點
@@ -239,7 +243,7 @@ Python `quote`(空白編為 `%20`)與 JS `encodeURIComponent` 不屬於官
239
243
  | `sdt` | 消費者電話 | 20 | | 純數字如 `0911123123`;搭配超商取貨時到店會發簡訊 |
240
244
  | `note1` / `note2` | 備註 | 400 | | 交易完成時原樣回傳;不可有 `*'<>[]"` |
241
245
  | `lgs_flag` | 物流啟用 | 1 | 條件 | `0`/不帶=不啟用、`1`=啟用。**`card_type=09` 時必須為 1**;**訂單金額 > 2 萬元無法使用物流** |
242
- | `store_type` | 超商類型 | 1 | 條件 | `0`/不帶=全部、`1`=7-11、`2`=全家、`4`=萊爾富(手冊 v1.1.1 移除 `3` OK)|
246
+ | `store_type` | 超商類型 | 1 | 條件 | `0`/不帶=全部、`1`=7-11、`2`=全家、`4`=萊爾富(超商取貨付款不再支援 OK,手冊 v1.1.1 移除 `3`;紅陽客服回覆 2026-09-29)|
243
247
  | `buyer_cid` | 買方統編 | 8 | | 隨交易開發票用 |
244
248
  | `carrier_type` | 載具類型 | 1 | | `1` 手機條碼、`2` 自然人憑證 |
245
249
  | `carrier_id` | 載具號碼 | 16 | 條件 | `carrier_type=1/2` 時必填 |
@@ -382,7 +386,7 @@ Python `quote`(空白編為 `%20`)與 JS `encodeURIComponent` 不屬於官
382
386
 
383
387
  欄位:`trade_no`、`web`、`Td`(⚠️ **大寫 T**,與請求端的 `td` 不同)、`note1`、`note2`、`SendType`(`1`=背景傳送)、`CargoNo`(寄件代碼)、`StoreType`(物流狀態代碼)、`StoreMsg`(狀態文字說明)、`ChkValue`(檢查碼)。
384
388
 
385
- > ⚠️ **手冊未提供 `StoreType` 的代碼對照表**,只說明「物流狀態之代碼」。實務上需以 `StoreMsg` 的文字說明為主,或洽紅陽索取代碼表。
389
+ > `StoreType` **沒有另外的代碼對照表**;每次通知都會同時回傳中文狀態說明 `StoreMsg`,以 `StoreMsg` 判讀即可(紅陽客服回覆 2026-09-29)。
386
390
 
387
391
  ### 測試環境的模擬方式(附錄 1)
388
392
 
@@ -418,7 +422,7 @@ Python `quote`(空白編為 `%20`)與 JS `encodeURIComponent` 不屬於官
418
422
 
419
423
  ## 8. 串接流程
420
424
 
421
- 1. 申請測試帳號
425
+ 1. 自行註冊測試帳號(§2「測試環境申請」)
422
426
  2. 下載串接手冊及 sample code
423
427
  3. 串接購物車(或自建)
424
428
 
@@ -433,8 +437,8 @@ Python `quote`(空白編為 `%20`)與 JS `encodeURIComponent` 不屬於官
433
437
  | 項目 | 官方 skill v1.1.1 | 手冊 |
434
438
  |---|---|---|
435
439
  | 對應手冊版本 | 標示依手冊 v1.1.0 校對 | 現行 v1.1.1(2026-08-19) |
436
- | `store_type` | 仍列 `3`=OK | v1.1.1 已移除 `3` |
437
- | `check_value` 的 URL encode | PHP `urlencode` 語意 | v1.1.0 附錄 3 要求 Java `URLEncoder`;v1.1.1 刪除附錄 3(見 §3.2) |
440
+ | `store_type` | 仍列 `3`=OK | v1.1.1 已移除 `3`;超商取貨付款不再支援 OK(紅陽客服回覆 2026-09-29) |
441
+ | `check_value` 的 URL encode | PHP `urlencode` 語意 | v1.1.1 可不做 URLEncode,做了也相容(紅陽客服回覆 2026-09-29;見 §3.2) |
438
442
  | CallBack 補發 | 30 分鐘內重送 5 次 | 30 分鐘內每 5 分鐘補發一次(§4.3.3) |
439
443
 
440
444
  官方 skill 附的 `check_value` 自檢向量(`0994ecc3…671d`)已用 `examples/sunpay-payment-example.py` 驗證相符。
@@ -443,14 +447,16 @@ Python `quote`(空白編為 `%20`)與 JS `encodeURIComponent` 不屬於官
443
447
 
444
448
  | 項目 | 備註 |
445
449
  |---|---|
446
- | 物流貨態 `StoreType` 代碼表 | 手冊只說是「物流狀態之代碼」,未附對照,需洽紅陽索取 |
447
450
  | 統一錯誤碼表 | 手冊無獨立錯誤碼章節,各 API 的 `pay_result`/`code` 已收錄於 §6 |
448
451
 
452
+ 已由紅陽確認、不再待補:`StoreType` 無代碼表(以 `StoreMsg` 為準)、目前無物流 API(紅陽客服回覆 2026-09-29)。
453
+
449
454
  電子發票側見 [../../taiwan-invoice/references/SUNPAY_API_REFERENCE.md](../../taiwan-invoice/references/SUNPAY_API_REFERENCE.md)。
450
455
 
451
456
  ## 11. 來源
452
457
 
453
458
  - 開發者專區 — https://www.sunpay.com.tw/developers/
459
+ - 紅陽客服回覆 2026-09-29(service@esafe.com.tw 轉客服 mandy@esafe.com.tw):簽章 URLEncode、OK 超商、StoreType、物流 API、測試帳號
454
460
  - 金流技術串接手冊 v1.1.1 — `https://storage.googleapis.com/joinchill-image/sunpay_techdoc/202608/紅陽科技金流服務-金流技術串接手冊V1.1.1.pdf`
455
461
  - 金流 AI 串接指南(Claude Code Skill)v1.1.1 — `https://storage.googleapis.com/joinchill-image/sunpay_techdoc/202608/sunpay-payment-skill-v1.1.1-v1.zip`
456
462
  - 金流範例程式 PHP/JAVA — `https://storage.googleapis.com/joinchill-image/sunpay_techdoc/202603/金流範例程式SampleCode_PHP.zip`、`…/金流範例程式SampleCode_JAVA.zip`
@@ -3,10 +3,10 @@
3
3
  "displayName": "Codex CLI",
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
- "root": ".codex",
6
+ "root": ".agents",
7
7
  "skillPath": "skills/taiwan-payment",
8
8
  "filename": "SKILL.md",
9
- "globalRoot": "~/.codex"
9
+ "globalRoot": "~/.agents"
10
10
  },
11
11
  "scriptPath": "skills/taiwan-payment/scripts",
12
12
  "frontmatter": {
package/dist/index.js CHANGED
@@ -16037,7 +16037,7 @@ function getAITypeDescription(aiType) {
16037
16037
  case "kiro":
16038
16038
  return "Kiro (.kiro/skills/)";
16039
16039
  case "codex":
16040
- return "Codex CLI (.codex/skills/)";
16040
+ return "Codex CLI (.agents/skills/)";
16041
16041
  case "qoder":
16042
16042
  return "Qoder (.qoder/skills/)";
16043
16043
  case "cline":
@@ -16327,7 +16327,7 @@ var PLATFORMS = [
16327
16327
  { name: "antigravity", folder: ".agent", description: "Antigravity (Google)" },
16328
16328
  { name: "copilot", folder: ".github", description: "GitHub Copilot" },
16329
16329
  { name: "kiro", folder: ".kiro", description: "Kiro (AWS)" },
16330
- { name: "codex", folder: ".codex", description: "Codex CLI (OpenAI)" },
16330
+ { name: "codex", folder: ".agents", description: "Codex CLI (OpenAI)" },
16331
16331
  { name: "qoder", folder: ".qoder", description: "Qodo (Qoder)" },
16332
16332
  { name: "cline", folder: ".cline", description: "Cline" },
16333
16333
  { name: "gemini", folder: ".gemini", description: "Gemini CLI" },
@@ -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.9";
16361
+ var VERSION = "1.5.10";
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.9",
3
+ "version": "1.5.10",
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",