taiwan-payment-skill 1.4.0 → 1.5.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.
- package/README.md +1 -1
- package/assets/taiwan-payment/CLAUDE.md +2 -2
- package/assets/taiwan-payment/EXAMPLES.md +72 -0
- package/assets/taiwan-payment/data/error-codes.csv +10 -0
- package/assets/taiwan-payment/data/field-mappings.csv +20 -18
- package/assets/taiwan-payment/data/providers.csv +1 -1
- package/assets/taiwan-payment/data/reasoning.csv +2 -0
- package/assets/taiwan-payment/data/troubleshooting.csv +6 -0
- package/assets/taiwan-payment/examples/jkopay-payment-example.py +319 -0
- package/assets/taiwan-payment/examples/sunpay-payment-example.py +296 -0
- package/assets/taiwan-payment/references/jkopay-payment-api.md +157 -15
- package/assets/taiwan-payment/scripts/core.py +4 -2
- package/assets/templates/platforms/{roocode.json → cline.json} +6 -5
- package/assets/templates/platforms/copilot.json +1 -1
- package/assets/templates/platforms/kiro.json +1 -1
- package/dist/index.js +10 -10
- package/package.json +1 -1
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 ·
|
|
112
|
+
Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
|
|
113
113
|
|
|
114
114
|
## 相關套件
|
|
115
115
|
|
|
@@ -51,7 +51,7 @@ taiwan-payment/ # Source of Truth
|
|
|
51
51
|
├── providers.csv # 14 providers(含 doc_access 文件公開程度分級)
|
|
52
52
|
├── operations.csv # 8 API operations
|
|
53
53
|
├── error-codes.csv # 120 error codes + solutions(11 家)
|
|
54
|
-
├── field-mappings.csv #
|
|
54
|
+
├── field-mappings.csv # 19 欄位 × 14 家 provider 對照
|
|
55
55
|
├── payment-methods.csv # 40 payment methods
|
|
56
56
|
├── reasoning.csv # 30+ recommendation rules
|
|
57
57
|
└── troubleshooting.csv # 16 troubleshooting cases
|
|
@@ -116,7 +116,7 @@ When modifying files:
|
|
|
116
116
|
| Kiro | `.kiro` | full |
|
|
117
117
|
| Codex | `.codex` | full |
|
|
118
118
|
| Qoder | `.qoder` | full |
|
|
119
|
-
|
|
|
119
|
+
| Cline | `.cline` | full |
|
|
120
120
|
| Gemini | `.gemini` | full |
|
|
121
121
|
| Trae | `.trae` | full |
|
|
122
122
|
| OpenCode | `.opencode` | full |
|
|
@@ -1537,6 +1537,78 @@ TapPay 是 **PCI 隔離設計**:前端 SDK 取 Prime(60 秒 TTL)→ 後端
|
|
|
1537
1537
|
3. **重複扣款**:`pay-by-prime` 帶 `remember=true` 後,回應內 `card_secret` 含 `card_key + card_token`,存起來下次直接 `pay-by-card-token`,免再過 SDK。適合訂閱與快速結帳。
|
|
1538
1538
|
4. **status=0 才是成功**:別只看 HTTP 200;TapPay HTTP 200 但 status≠0 是業務失敗。
|
|
1539
1539
|
|
|
1540
|
+
## O'Pay 歐付寶範例
|
|
1541
|
+
|
|
1542
|
+
**與 ECPay 同源**——`MerchantID` + 排序後 urlencode + SHA256 的 `CheckMacValue`,欄位名幾乎完全一致。已有 ECPay 實作者,**換網域即可**:
|
|
1543
|
+
|
|
1544
|
+
```python
|
|
1545
|
+
# ECPay
|
|
1546
|
+
https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
|
|
1547
|
+
# O'Pay:只換網域,CheckMacValue 演算法與參數名不變
|
|
1548
|
+
https://payment-stage.opay.tw/Cashier/AioCheckOut/V5
|
|
1549
|
+
```
|
|
1550
|
+
|
|
1551
|
+
實作直接沿用 [`examples/ecpay-payment-example.py`](examples/ecpay-payment-example.py),把 base URL 與金鑰換掉即可。
|
|
1552
|
+
|
|
1553
|
+
### O'Pay 獨有、ECPay 沒有的
|
|
1554
|
+
|
|
1555
|
+
| 能力 | 說明 |
|
|
1556
|
+
|---|---|
|
|
1557
|
+
| `AccountLink` | 銀行快付 |
|
|
1558
|
+
| `TopUpUsed` | 儲值消費 |
|
|
1559
|
+
| `WeiXinpay` | 微信支付(線上線下)|
|
|
1560
|
+
| `HoldTradeAMT=1` | **延遲撥款**,款項先留在歐付寶,確認出貨後再申請撥款——做代收代付或擔保交易時很有用 |
|
|
1561
|
+
|
|
1562
|
+
## 街口支付 JKOPAY 範例
|
|
1563
|
+
|
|
1564
|
+
### 完整 Python 範例
|
|
1565
|
+
請見 [`examples/jkopay-payment-example.py`](examples/jkopay-payment-example.py) — 涵蓋 Entry / Refund / Inquiry / 授權扣款(綁定、發動、終止),並內建**官方測試向量的自我驗證**(直接執行即可確認你的環境算出的 digest 與街口一致,不會發網路請求)。
|
|
1566
|
+
|
|
1567
|
+
### 五大要點
|
|
1568
|
+
|
|
1569
|
+
1. **簽的是 payload 原始字串**,不排序、不 urlencode。這與 ECPay 的 `CheckMacValue` 完全不同路數,從綠界遷移最容易卡在這。
|
|
1570
|
+
2. **連空白都算數**。官方範例 `"currency": "TWD"` 冒號後有空格,拿掉 digest 就變。**先組好字串、簽它、原封不動送出**,不要簽完再用另一次 `json.dumps()` 產生 body。
|
|
1571
|
+
3. **街口有三套簽章**(線上支付/POS/OAuth),程式碼不可共用。見 [reference §7](references/jkopay-payment-api.md)。
|
|
1572
|
+
4. **對帳用 `debit_amount` 不是 `final_price`**。街口幣與券折抵不進撥款,用 `final_price` 對帳會長期短差。
|
|
1573
|
+
5. **授權扣款有六個硬限制**,其中兩個直接約束排程設計:`306` 扣款只能在 **08:00–20:00** 發動(夜間 batch 必失敗)、`307` 同一 `auth_no` **不可併發**(扣款必須序列化)。
|
|
1574
|
+
|
|
1575
|
+
### 一個資料庫層的地雷
|
|
1576
|
+
|
|
1577
|
+
`payment_url` 與 `qr_img` 的**長度會超過 255**,欄位不要開 `VARCHAR(255)`。
|
|
1578
|
+
|
|
1579
|
+
## 紅陽科技 SunPay 範例
|
|
1580
|
+
|
|
1581
|
+
### 完整 Python 範例
|
|
1582
|
+
請見 [`examples/sunpay-payment-example.py`](examples/sunpay-payment-example.py) — 涵蓋 `rsamsg` 加解密、`check_value` 簽章、`send_time` 組法、兩張 `pay_result` 對照表、物流通知解析,並內建**官方測試向量的自我驗證**。
|
|
1583
|
+
|
|
1584
|
+
### 四大要點
|
|
1585
|
+
|
|
1586
|
+
1. **14 家中唯一使用非對稱加密**。RSA 分段加密 + SHA256 簽章,既有的 SHA256 檢查碼或 AES 程式碼一律不能沿用。
|
|
1587
|
+
2. **加密分段 117、解密分段 128**——兩者不同。128 是 1024-bit RSA 的密文區塊長度,117 = 128 − 11(PKCS#1 v1.5 padding)。誤寫成同一個值是最常見的錯。
|
|
1588
|
+
3. **`send_time` 格式是反的**:`fffssmmHHyyyyMMdd`,毫秒在最前面、日期在最後。且**超過 120 秒即無效**,主機要 NTP 校時。
|
|
1589
|
+
4. **SHA2 密鑰接在字串尾端**,不是 ECPay 那種 `HashKey=...&參數&HashIV=...` 前後包夾。且 `null` 值的參數不參與簽名。
|
|
1590
|
+
|
|
1591
|
+
### ⚠️ 最容易踩的一致性陷阱
|
|
1592
|
+
|
|
1593
|
+
同一個欄位名 `pay_result`、同一個值 `12`:
|
|
1594
|
+
|
|
1595
|
+
| API | `12` 的意思 |
|
|
1596
|
+
|---|---|
|
|
1597
|
+
| 交易 CallBack | **已建立** |
|
|
1598
|
+
| 查詢 API | **查無該筆訂單** |
|
|
1599
|
+
|
|
1600
|
+
**兩張代碼表必須分開維護,絕不可共用同一份 mapping。** 範例檔中已拆成 `CALLBACK_RESULT` 與 `QUERY_RESULT` 兩個字典並附自我驗證。
|
|
1601
|
+
|
|
1602
|
+
### 其他
|
|
1603
|
+
|
|
1604
|
+
- 交易與查詢是 `/v4/`,但**請款與退款仍是 `/v3/`**——同一份手冊裡版號不一致,不是筆誤
|
|
1605
|
+
- 物流狀態通知是 **HTTP FORM POST key-value(非 JSON)**且全欄位經 URL Encode,另訂單編號欄位是**大寫 `Td`**
|
|
1606
|
+
- 回傳網址**不可帶 port**,會被資安風控擋掉;CallBack **僅補發 30 分鐘**(每 5 分鐘一次),需另實作查詢對帳
|
|
1607
|
+
|
|
1608
|
+
## GoMyPay 範例
|
|
1609
|
+
|
|
1610
|
+
尚無範例——目前只取得服務層資訊,參數層需洽客服取得完整 API 文件。見 [reference](references/gomypay-payment-api.md)。
|
|
1611
|
+
|
|
1540
1612
|
---
|
|
1541
1613
|
|
|
1542
1614
|
**更多範例持續更新中...**
|
|
@@ -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 重送 不可換號
|
|
@@ -1,18 +1,20 @@
|
|
|
1
|
-
field_name,field_zh,ecpay_name,newebpay_name,payuni_name,smilepay_name,pchomepay_name,ezpay_name,paynow_name,shopline_name,linepay_name,tappay_name,type,required,notes
|
|
2
|
-
merchant_id,商店代號,MerchantID,MerchantID,MerID,Dcvc,APP_ID (Basic Auth),MerchantID_,merID,merchantId,channelId,merchant_id,string,true,各家欄位名稱不同;ezPay 後綴底線;PChomePay 用 Basic Auth;TapPay 在 body
|
|
3
|
-
order_id,訂單編號,MerchantTradeNo,MerchantOrderNo,MerTradeNo,Data_id,order_id,MerchantOrderNo,paymentNo,referenceNumber,orderId,order_number,string,true,需唯一;SmilePay/Shopline/LINEPay 限 30+ 字元
|
|
4
|
-
order_date,訂單日期,MerchantTradeDate,TimeStamp,TradeTime,(系統決定),(系統決定),TimeStamp,(系統決定),(系統決定),(系統決定),(系統決定),string,true,ECPay 用 yyyy/MM/dd HH:mm:ss;其他多用 unix timestamp
|
|
5
|
-
amount,交易金額,TotalAmount,Amt,TradeAmt,Amount,amount,Amt,amount,amount.value (cents!),amount,amount,integer,true,Shopline 用分為單位 (NT$1000=100000);其他用元
|
|
6
|
-
description,交易描述,TradeDesc,ItemDesc,ProdDesc,od_sob,(無),ItemDesc,description,description,(no field),details,string,true,需 URL Encode (ECPay)
|
|
7
|
-
item_name,商品名稱,ItemName,ItemDesc,ProdDesc,od_sob,(無),ItemName,(via order),items[],(no field),details,string,true,多項分隔符: ECPay # SmilePay 與 ezPay |
|
|
8
|
-
return_url,背景通知,ReturnURL,NotifyURL,NotifyURL,Roturl,return_url,NotifyURL,webhookUrl,webhookUrl,(no field),notify_url,string,true,HTTPS only;PayNow 現代版用 webhookUrl
|
|
9
|
-
client_back_url,前台返回,ClientBackURL,ReturnURL,ReturnURL,Roturl_status,(無),ReturnURL,resultUrl,returnUrl,confirmUrl,frontend_redirect_url (in result_url),string,false,客戶完成後導回
|
|
10
|
-
payment_type,付款方式,ChoosePayment,PaymentType / channelid,PayType,Pay_zg,pay_type,PaymentType,paymentMethodType,paymentMethods[],(only LINE Pay),(only credit),string,true,各家 enum 不同;ECPay 看 ChoosePayment 表
|
|
11
|
-
check_value,檢查碼/簽章,CheckMacValue,CheckValue,CheckSum,Mid_smilepay (反推加權檢核碼),(no field — 用 token),CheckValue (sha256),X-LINE-Authorization (HMAC),x-slp-signature (HMAC webhook),X-LINE-Authorization (HMAC),(no field; uses Partner Key),string,true,SHA256;TapPay 用 Partner Key in header
|
|
12
|
-
encrypt_type,加密 / Version,EncryptType,Version,Version,Verify_key,(token-based),Version (固定 2.0),(no field),Version,(no field),(no field),string,true,ECPay 固定 1;NewebPay 2.0 / 2.3;ezPay 2.0
|
|
13
|
-
trade_no,平台交易編號,TradeNo,TradeNo,PayUniTradeNo,PaymentNo,(返回 order_id),TradeNo,id (PaymentIntent),id,transactionId,rec_trade_id,string,false,平台回傳的內部編號;列印時需要
|
|
14
|
-
rtn_code,回傳代碼,RtnCode,Status,Status,Status,code,Status,status / type,status,returnCode,status,string,false,各家不同 — 0/1/SUCCESS/Success;TapPay 用 0=success
|
|
15
|
-
rtn_msg,回傳訊息,RtnMsg,Message,Message,Desc,message,Message,message,error / message,returnMessage,msg,string,false,中文訊息;錯誤時帶
|
|
16
|
-
buyer_email,買方信箱,(no field),Email,Email,Email,(via cardholder),Email,(via customer obj),customer.email,(no field),cardholder.email,string,false,
|
|
17
|
-
card_token,記憶卡 token,(via 定期定額),TokenValue,token,(無),(無),TokenValue,(via Customer.cards[]),(via card object),(no field),card_token,string,false,需另申請;用於重複扣款
|
|
18
|
-
card_key,記憶卡 key,(無),(無),(無),(無),(無),(無),(via Customer),(via card object),(no field),card_key,string,false,TapPay 獨有;搭配 card_token 用
|
|
1
|
+
field_name,field_zh,ecpay_name,newebpay_name,payuni_name,smilepay_name,pchomepay_name,ezpay_name,paynow_name,shopline_name,linepay_name,tappay_name,opay_name,jkopay_name,sunpay_name,gomypay_name,type,required,notes
|
|
2
|
+
merchant_id,商店代號,MerchantID,MerchantID,MerID,Dcvc,APP_ID (Basic Auth),MerchantID_,merID,merchantId,channelId,merchant_id,MerchantID,store_id,web,(待補),string,true,各家欄位名稱不同;ezPay 後綴底線;PChomePay 用 Basic Auth;TapPay 在 body
|
|
3
|
+
order_id,訂單編號,MerchantTradeNo,MerchantOrderNo,MerTradeNo,Data_id,order_id,MerchantOrderNo,paymentNo,referenceNumber,orderId,order_number,MerchantTradeNo,platform_order_id,td,(待補),string,true,需唯一;SmilePay/Shopline/LINEPay 限 30+ 字元
|
|
4
|
+
order_date,訂單日期,MerchantTradeDate,TimeStamp,TradeTime,(系統決定),(系統決定),TimeStamp,(系統決定),(系統決定),(系統決定),(系統決定),MerchantTradeDate,(系統決定),send_time (fffssmmHHyyyyMMdd),(待補),string,true,ECPay 用 yyyy/MM/dd HH:mm:ss;其他多用 unix timestamp
|
|
5
|
+
amount,交易金額,TotalAmount,Amt,TradeAmt,Amount,amount,Amt,amount,amount.value (cents!),amount,amount,TotalAmount,final_price (另有 total_price 原價),mn,(待補),integer,true,Shopline 用分為單位 (NT$1000=100000);其他用元
|
|
6
|
+
description,交易描述,TradeDesc,ItemDesc,ProdDesc,od_sob,(無),ItemDesc,description,description,(no field),details,TradeDesc,(無),order_info,(待補),string,true,需 URL Encode (ECPay)
|
|
7
|
+
item_name,商品名稱,ItemName,ItemDesc,ProdDesc,od_sob,(無),ItemName,(via order),items[],(no field),details,ItemName,products[].name,order_info,(待補),string,true,多項分隔符: ECPay # SmilePay 與 ezPay |
|
|
8
|
+
return_url,背景通知,ReturnURL,NotifyURL,NotifyURL,Roturl,return_url,NotifyURL,webhookUrl,webhookUrl,(no field),notify_url,ReturnURL,result_url,交易結果通知網址 (後台設定),(待補),string,true,HTTPS only;PayNow 現代版用 webhookUrl
|
|
9
|
+
client_back_url,前台返回,ClientBackURL,ReturnURL,ReturnURL,Roturl_status,(無),ReturnURL,resultUrl,returnUrl,confirmUrl,frontend_redirect_url (in result_url),ClientBackURL,result_display_url,交易完成轉導網址 (後台設定),(待補),string,false,客戶完成後導回
|
|
10
|
+
payment_type,付款方式,ChoosePayment,PaymentType / channelid,PayType,Pay_zg,pay_type,PaymentType,paymentMethodType,paymentMethods[],(only LINE Pay),(only credit),ChoosePayment,(無;街口單一),card_type,(待補),string,true,各家 enum 不同;ECPay 看 ChoosePayment 表
|
|
11
|
+
check_value,檢查碼/簽章,CheckMacValue,CheckValue,CheckSum,Mid_smilepay (反推加權檢核碼),(no field — 用 token),CheckValue (sha256),X-LINE-Authorization (HMAC),x-slp-signature (HMAC webhook),X-LINE-Authorization (HMAC),(no field; uses Partner Key),CheckMacValue,digest (HMAC-SHA256 header),check_value (SHA256) + rsamsg (RSA),(待補),string,true,SHA256;TapPay 用 Partner Key in header
|
|
12
|
+
encrypt_type,加密 / Version,EncryptType,Version,Version,Verify_key,(token-based),Version (固定 2.0),(no field),Version,(no field),(no field),EncryptType,(無),(無),(待補),string,true,ECPay 固定 1;NewebPay 2.0 / 2.3;ezPay 2.0
|
|
13
|
+
trade_no,平台交易編號,TradeNo,TradeNo,PayUniTradeNo,PaymentNo,(返回 order_id),TradeNo,id (PaymentIntent),id,transactionId,rec_trade_id,TradeNo,tradeNo,trade_no,(待補),string,false,平台回傳的內部編號;列印時需要
|
|
14
|
+
rtn_code,回傳代碼,RtnCode,Status,Status,Status,code,Status,status / type,status,returnCode,status,RtnCode,result (字串 000),pay_result,(待補),string,false,各家不同 — 0/1/SUCCESS/Success;TapPay 用 0=success
|
|
15
|
+
rtn_msg,回傳訊息,RtnMsg,Message,Message,Desc,message,Message,message,error / message,returnMessage,msg,RtnMsg,message,StatusDesc / message,(待補),string,false,中文訊息;錯誤時帶
|
|
16
|
+
buyer_email,買方信箱,(no field),Email,Email,Email,(via cardholder),Email,(via customer obj),customer.email,(no field),cardholder.email,(無欄位),(無),email,(待補),string,false,
|
|
17
|
+
card_token,記憶卡 token,(via 定期定額),TokenValue,token,(無),(無),TokenValue,(via Customer.cards[]),(via card object),(no field),card_token,(via 定期定額),(無;走授權扣款 auth_no),save_card_token,(待補),string,false,需另申請;用於重複扣款
|
|
18
|
+
card_key,記憶卡 key,(無),(無),(無),(無),(無),(無),(via Customer),(via card object),(no field),card_key,(無),(無),(無;token 即識別),(待補),string,false,TapPay 獨有;搭配 card_token 用
|
|
19
|
+
signature_algo,簽章/加密演算法,SHA256 (參數排序+URLEncode),AES-256-CBC + SHA256,AES-256-GCM + SHA256 (須附16-byte tag),共享密鑰 + 加權檢核碼 (無 AES),Basic Auth -> pcpay-token (8h),AES-256-CBC + SHA256 (同 NewebPay),JWT Bearer (現代) / 3DES 動態金鑰 (傳統),Header 認證 + HMAC-SHA256 (webhook),HMAC-SHA256 (X-LINE-Authorization),Prime -> pay-by-prime (無自簽),SHA256 (同 ECPay CheckMacValue),HMAC-SHA256 / SHA256 三套並存 (見 reference §7),RSA 分段加密(117/128) + SHA256 簽章,(待補),string,Y,選型與工時評估用。ECPay/O'Pay 同源可共用程式碼;NewebPay/ezPay 同源;紅陽是唯一非對稱加密;街口三個模組三套不可共用
|
|
20
|
+
invoice_carrier,發票載具(手機條碼),(金流端無;發票 API 用 CarrierType+CarrierNum),(未驗證),(未驗證),(未驗證),(未驗證),(未驗證),(未驗證),(未驗證),(未驗證),(未驗證),(金流端無;發票 API 用 CarrierType+CarrierNum),invoice_vehicle (OnlinePay) / InvoiceVehicle (POS) / phone_barcode (OAuth),carrier_type + carrier_id (隨交易開票),(待補),string,N,金流回傳的載具可直接餵給發票 API 的 CarrierType=3 流程。⚠️ 街口在三個模組用了三個不同欄位名。標(未驗證)者為尚未查證非確定無此欄位
|
|
@@ -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
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
街口支付 JKOPAY Python 範例
|
|
4
|
+
|
|
5
|
+
依照 taiwan-payment-skill 規範撰寫。
|
|
6
|
+
|
|
7
|
+
⚠️ 街口有三套互不相容的簽章機制,本檔涵蓋的是「線上支付 OnlinePay」與
|
|
8
|
+
「授權扣款」共用的那一套(HMAC-SHA256 簽 payload 原文)。
|
|
9
|
+
線下 POS 與 inApp OAuth 是另外兩套,不可共用本檔的 sign()。
|
|
10
|
+
詳見 references/jkopay-payment-api.md §7。
|
|
11
|
+
|
|
12
|
+
支援:
|
|
13
|
+
- Entry API 建立訂單取得付款網址(冪等)
|
|
14
|
+
- Refund API 退款(支援多次部分退款)
|
|
15
|
+
- Inquiry API 查詢(一次最多 20 筆)
|
|
16
|
+
- Authpay 授權扣款:綁定 / 發動扣款 / 終止
|
|
17
|
+
|
|
18
|
+
API 文件: 參見 references/jkopay-payment-api.md
|
|
19
|
+
|
|
20
|
+
依賴:
|
|
21
|
+
pip install requests
|
|
22
|
+
|
|
23
|
+
直接執行本檔會跑官方測試向量的自我驗證,不會發出任何網路請求:
|
|
24
|
+
python jkopay-payment-example.py
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import hashlib
|
|
28
|
+
import hmac
|
|
29
|
+
import json
|
|
30
|
+
from dataclasses import dataclass, field
|
|
31
|
+
from typing import Any, Dict, List, Optional
|
|
32
|
+
|
|
33
|
+
import requests
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
# ============================================================================
|
|
37
|
+
# 簽章
|
|
38
|
+
# ============================================================================
|
|
39
|
+
|
|
40
|
+
def sign(payload: str, secret_key: str) -> str:
|
|
41
|
+
"""產生 digest。
|
|
42
|
+
|
|
43
|
+
⚠️ 簽的是 **payload 原始字串本身**——不排序、不做 URL encode。
|
|
44
|
+
這與 ECPay 的 CheckMacValue(排序 + urlencode + SHA256)完全不同路數,
|
|
45
|
+
從綠界遷移過來最容易在這裡卡住。
|
|
46
|
+
|
|
47
|
+
⚠️ 連空白都算數。官方範例的 `"currency": "TWD"` 冒號後有一個空格,
|
|
48
|
+
把它拿掉 digest 就完全不同。因此**送出的 bytes 必須與簽章的 bytes
|
|
49
|
+
逐字元相同**——先組好字串、簽它、然後原封不動送出,
|
|
50
|
+
不要簽完再用另一次 json.dumps() 產生 body。
|
|
51
|
+
"""
|
|
52
|
+
return hmac.new(
|
|
53
|
+
secret_key.encode('utf-8'),
|
|
54
|
+
payload.encode('utf-8'),
|
|
55
|
+
hashlib.sha256,
|
|
56
|
+
).hexdigest()
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
# ============================================================================
|
|
60
|
+
# Client
|
|
61
|
+
# ============================================================================
|
|
62
|
+
|
|
63
|
+
@dataclass
|
|
64
|
+
class JkopayConfig:
|
|
65
|
+
host: str # 街口簽約時提供,例:https://onlinepay.jkopay.com
|
|
66
|
+
api_key: str
|
|
67
|
+
secret_key: str
|
|
68
|
+
store_id: str
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class JkopayClient:
|
|
72
|
+
def __init__(self, config: JkopayConfig, timeout: int = 15):
|
|
73
|
+
self.config = config
|
|
74
|
+
self.timeout = timeout
|
|
75
|
+
|
|
76
|
+
# ---- 內部 ----
|
|
77
|
+
|
|
78
|
+
def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
|
|
79
|
+
# 先序列化成字串並固定下來,簽它、送它 —— 全程只有這一份 bytes
|
|
80
|
+
payload = json.dumps(body, ensure_ascii=False, separators=(',', ':'))
|
|
81
|
+
resp = requests.post(
|
|
82
|
+
f'{self.config.host}{path}',
|
|
83
|
+
data=payload.encode('utf-8'),
|
|
84
|
+
headers={
|
|
85
|
+
'Content-Type': 'application/json',
|
|
86
|
+
'api-key': self.config.api_key,
|
|
87
|
+
'digest': sign(payload, self.config.secret_key),
|
|
88
|
+
},
|
|
89
|
+
timeout=self.timeout,
|
|
90
|
+
)
|
|
91
|
+
resp.raise_for_status()
|
|
92
|
+
return resp.json()
|
|
93
|
+
|
|
94
|
+
def _get(self, path: str, query: str) -> Dict[str, Any]:
|
|
95
|
+
# GET 簽的是 query string 原文(不含 ?)
|
|
96
|
+
resp = requests.get(
|
|
97
|
+
f'{self.config.host}{path}?{query}',
|
|
98
|
+
headers={
|
|
99
|
+
'api-key': self.config.api_key,
|
|
100
|
+
'digest': sign(query, self.config.secret_key),
|
|
101
|
+
},
|
|
102
|
+
timeout=self.timeout,
|
|
103
|
+
)
|
|
104
|
+
resp.raise_for_status()
|
|
105
|
+
return resp.json()
|
|
106
|
+
|
|
107
|
+
# ---- 線上支付 ----
|
|
108
|
+
|
|
109
|
+
def create_order(
|
|
110
|
+
self,
|
|
111
|
+
platform_order_id: str,
|
|
112
|
+
total_price: int,
|
|
113
|
+
final_price: int,
|
|
114
|
+
result_url: str,
|
|
115
|
+
result_display_url: str,
|
|
116
|
+
*,
|
|
117
|
+
currency: str = 'TWD',
|
|
118
|
+
unredeem: int = 0,
|
|
119
|
+
valid_time: Optional[str] = None,
|
|
120
|
+
confirm_url: Optional[str] = None,
|
|
121
|
+
payment_type: str = 'onetime',
|
|
122
|
+
) -> Dict[str, Any]:
|
|
123
|
+
"""建立訂單,取得付款網址。
|
|
124
|
+
|
|
125
|
+
冪等:同一個 platform_order_id 在付款完成前重複呼叫,
|
|
126
|
+
會回同一個付款網址,不會產生第二筆訂單。
|
|
127
|
+
|
|
128
|
+
⚠️ result_object.payment_url 與 qr_img 的長度會超過 255,
|
|
129
|
+
資料庫欄位不要開 VARCHAR(255)。
|
|
130
|
+
⚠️ 付款網址僅 20 分鐘有效;只要還在 valid_time 內,
|
|
131
|
+
可用同一單號再呼叫本方法展延另一個 20 分鐘。
|
|
132
|
+
"""
|
|
133
|
+
body: Dict[str, Any] = {
|
|
134
|
+
'platform_order_id': platform_order_id,
|
|
135
|
+
'store_id': self.config.store_id,
|
|
136
|
+
'currency': currency,
|
|
137
|
+
'total_price': total_price,
|
|
138
|
+
'final_price': final_price,
|
|
139
|
+
'unredeem': unredeem,
|
|
140
|
+
'result_url': result_url,
|
|
141
|
+
'result_display_url': result_display_url,
|
|
142
|
+
'payment_type': payment_type,
|
|
143
|
+
}
|
|
144
|
+
if valid_time:
|
|
145
|
+
body['valid_time'] = valid_time
|
|
146
|
+
if confirm_url:
|
|
147
|
+
body['confirm_url'] = confirm_url
|
|
148
|
+
return self._post('/platform/entry', body)
|
|
149
|
+
|
|
150
|
+
def refund(self, platform_order_id: str, refund_order_id: str, refund_amount: int) -> Dict[str, Any]:
|
|
151
|
+
"""退款。支援全額與多次部分退款,累積不可超過實際消費金額。
|
|
152
|
+
|
|
153
|
+
⚠️ refund_order_id 一筆只能退一次。重送同一個號碼**不是重試**,
|
|
154
|
+
會被視為已使用。網路逾時後要確認結果請改用 inquiry() 查,
|
|
155
|
+
**不要換號重送**——換號會變成第二筆退款。
|
|
156
|
+
"""
|
|
157
|
+
return self._post('/platform/refund', {
|
|
158
|
+
'platform_order_id': platform_order_id,
|
|
159
|
+
'refund_order_id': refund_order_id,
|
|
160
|
+
'refund_amount': refund_amount,
|
|
161
|
+
})
|
|
162
|
+
|
|
163
|
+
def inquiry(self, platform_order_ids: List[str]) -> Dict[str, Any]:
|
|
164
|
+
"""查詢訂單與退款歷程。一次最多 20 筆。
|
|
165
|
+
|
|
166
|
+
⚠️ 查無訂單時 result 仍為 '000',實際結果在
|
|
167
|
+
transactions[].status(102 = 訂單編號不存在)。
|
|
168
|
+
只判斷 result 會把不存在的訂單當成功。
|
|
169
|
+
"""
|
|
170
|
+
if len(platform_order_ids) > 20:
|
|
171
|
+
raise ValueError('Inquiry API 一次最多查 20 筆')
|
|
172
|
+
return self._get('/platform/inquiry', f'platform_order_ids={",".join(platform_order_ids)}')
|
|
173
|
+
|
|
174
|
+
# ---- 授權扣款(訂閱)----
|
|
175
|
+
|
|
176
|
+
def create_authpay(
|
|
177
|
+
self,
|
|
178
|
+
authpay_name: str,
|
|
179
|
+
billing_amount: int,
|
|
180
|
+
result_url: str,
|
|
181
|
+
*,
|
|
182
|
+
regular: bool = True,
|
|
183
|
+
period: str = 'month',
|
|
184
|
+
times: int = 1,
|
|
185
|
+
platform_authpay_id: Optional[str] = None,
|
|
186
|
+
) -> Dict[str, Any]:
|
|
187
|
+
"""建立授權綁定,取得 authpay_url 供消費者授權。
|
|
188
|
+
|
|
189
|
+
regular=True 定期定額(需帶 billing_cycle)
|
|
190
|
+
regular=False 不定期不定額(授權範圍內隨時扣款)
|
|
191
|
+
|
|
192
|
+
⚠️ times 上限:week / month / quarter 皆為 7,year 為 12。
|
|
193
|
+
「每月多次小額扣款」很容易撞上 month <= 7 這個限制。
|
|
194
|
+
"""
|
|
195
|
+
if period in ('week', 'month', 'quarter') and times > 7:
|
|
196
|
+
raise ValueError(f'{period} 的扣款次數上限為 7 次')
|
|
197
|
+
if period == 'year' and times > 12:
|
|
198
|
+
raise ValueError('year 的扣款次數上限為 12 次')
|
|
199
|
+
|
|
200
|
+
body: Dict[str, Any] = {
|
|
201
|
+
'authpay_name': authpay_name,
|
|
202
|
+
'store_id': self.config.store_id,
|
|
203
|
+
'billing_amount': billing_amount,
|
|
204
|
+
'billing_currency': 'TWD',
|
|
205
|
+
'result_url': result_url,
|
|
206
|
+
}
|
|
207
|
+
if platform_authpay_id:
|
|
208
|
+
body['platform_authpay_id'] = platform_authpay_id
|
|
209
|
+
if regular:
|
|
210
|
+
body['billing_cycle'] = {'period': period, 'times': times}
|
|
211
|
+
|
|
212
|
+
path = '/platform/authpay/regular' if regular else '/platform/authpay/limited'
|
|
213
|
+
return self._post(path, body)
|
|
214
|
+
|
|
215
|
+
def charge_authpay(
|
|
216
|
+
self,
|
|
217
|
+
auth_no: str,
|
|
218
|
+
platform_order_id: str,
|
|
219
|
+
trade_name: str,
|
|
220
|
+
total_price: int,
|
|
221
|
+
final_price: int,
|
|
222
|
+
) -> Dict[str, Any]:
|
|
223
|
+
"""以既有授權發動扣款。
|
|
224
|
+
|
|
225
|
+
⚠️ 六個硬限制,設計排程前務必知道(回應碼見 reference §6.6):
|
|
226
|
+
306 扣款只能在 08:00–20:00 (UTC+8) 發動 —— 夜間 batch 必失敗
|
|
227
|
+
307 同一 auth_no 同時只允許一筆付款 —— 扣款必須序列化
|
|
228
|
+
303 金額超過「消費者自己在 App 設定的額度」,商家不可控
|
|
229
|
+
304 final_price 必須等於授權時的 billing_amount
|
|
230
|
+
305 超過當期扣款次數上限
|
|
231
|
+
104 超過電支法規的個人月限額
|
|
232
|
+
|
|
233
|
+
trade_name 會顯示在消費者 App 的授權交易記錄頁,
|
|
234
|
+
寫得讓對方看得懂,否則容易被誤認為盜刷而取消授權。
|
|
235
|
+
"""
|
|
236
|
+
return self._post('/platform/authpay/transaction', {
|
|
237
|
+
'auth_no': auth_no,
|
|
238
|
+
'order': {
|
|
239
|
+
'platform_order_id': platform_order_id,
|
|
240
|
+
'trade_name': trade_name,
|
|
241
|
+
'currency': 'TWD',
|
|
242
|
+
'total_price': total_price,
|
|
243
|
+
'final_price': final_price,
|
|
244
|
+
},
|
|
245
|
+
})
|
|
246
|
+
|
|
247
|
+
def cancel_authpay(self, auth_no: str) -> Dict[str, Any]:
|
|
248
|
+
"""終止授權。重複取消會回 302 Canceled auth_no。"""
|
|
249
|
+
return self._post('/platform/authpay/cancel', {'auth_no': auth_no})
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
# ============================================================================
|
|
253
|
+
# 對帳
|
|
254
|
+
# ============================================================================
|
|
255
|
+
|
|
256
|
+
def settled_amount(transaction: Dict[str, Any]) -> int:
|
|
257
|
+
"""取得實際會進撥款的金額。
|
|
258
|
+
|
|
259
|
+
⚠️ 對帳要用 debit_amount 而不是 final_price。
|
|
260
|
+
街口幣與券折抵的部分(redeem_amount)不會進你的撥款帳,
|
|
261
|
+
直接用 final_price 對帳會長期短差。
|
|
262
|
+
|
|
263
|
+
恆等式:final_price = redeem_amount + debit_amount
|
|
264
|
+
"""
|
|
265
|
+
return int(transaction['debit_amount'])
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
# ============================================================================
|
|
269
|
+
# 自我驗證(官方測試向量)
|
|
270
|
+
# ============================================================================
|
|
271
|
+
|
|
272
|
+
def _self_test() -> int:
|
|
273
|
+
"""用街口官方文件的測試向量驗證 sign() 實作。
|
|
274
|
+
|
|
275
|
+
這兩組值直接取自官方「加簽加密說明」頁,可確認你的環境
|
|
276
|
+
(字元編碼、HMAC 實作)產生的 digest 與街口一致。
|
|
277
|
+
"""
|
|
278
|
+
secret = ('r0odDC1e9LHXDmxuvmOv9bgaWLf2CXB2c4gMheoFucVKNMi1K0Id9zwRHJF1r'
|
|
279
|
+
'-kdtAKriKgb11VDlo7Kb8R-FQ')
|
|
280
|
+
|
|
281
|
+
post_payload = (
|
|
282
|
+
'{"platform_order_id":"demo-order-001",'
|
|
283
|
+
'"store_id":"35f12dff-1581-11e9-a054-00505684fd45",'
|
|
284
|
+
'"currency": "TWD","total_price":10,"final_price":10,"unredeem":10,'
|
|
285
|
+
'"result_display_url":"https://display.com",'
|
|
286
|
+
'"result_url":"https://result-callback.xxx/xxx"}'
|
|
287
|
+
)
|
|
288
|
+
cases = [
|
|
289
|
+
('POST (Entry API)', post_payload,
|
|
290
|
+
'3577609b058ab85c2d0a00a5421a991979ed6b9f549476e9a82476dc1b70d876'),
|
|
291
|
+
('GET (Inquiry API)', 'platform_order_ids=test123,demo-order-001',
|
|
292
|
+
'7778b95890af17c5b41e8cef957f4769e7bfecc79e9f9ee555923293ebd8e880'),
|
|
293
|
+
]
|
|
294
|
+
|
|
295
|
+
failed = 0
|
|
296
|
+
print('街口官方測試向量驗證')
|
|
297
|
+
for label, payload, expected in cases:
|
|
298
|
+
got = sign(payload, secret)
|
|
299
|
+
ok = got == expected
|
|
300
|
+
failed += not ok
|
|
301
|
+
print(f' [{"PASS" if ok else "FAIL"}] {label}')
|
|
302
|
+
if not ok:
|
|
303
|
+
print(f' 期望 {expected}')
|
|
304
|
+
print(f' 實得 {got}')
|
|
305
|
+
|
|
306
|
+
# 示範空白的影響:把 `"currency": "TWD"` 的空格拿掉,digest 就變了
|
|
307
|
+
no_space = post_payload.replace('"currency": "TWD"', '"currency":"TWD"')
|
|
308
|
+
changed = sign(no_space, secret) != cases[0][2]
|
|
309
|
+
failed += not changed
|
|
310
|
+
print(f' [{"PASS" if changed else "FAIL"}] 移除一個空白後 digest 確實改變'
|
|
311
|
+
f'(證明必須逐字元一致)')
|
|
312
|
+
|
|
313
|
+
print()
|
|
314
|
+
print('全部通過' if failed == 0 else f'{failed} 項失敗')
|
|
315
|
+
return 1 if failed else 0
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
if __name__ == '__main__':
|
|
319
|
+
raise SystemExit(_self_test())
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
紅陽科技 SunPay Python 範例
|
|
4
|
+
|
|
5
|
+
依照 taiwan-payment-skill 規範撰寫。
|
|
6
|
+
|
|
7
|
+
⚠️ 紅陽是本 skill 收錄的 14 家中**唯一使用非對稱加密**的。
|
|
8
|
+
其他家不是 SHA256 檢查碼(ECPay / O'Pay)就是 AES 對稱加密
|
|
9
|
+
(NewebPay / PAYUNi / ezPay)。既有的加解密函式一律不能沿用。
|
|
10
|
+
|
|
11
|
+
送出的 form 只有四個欄位:
|
|
12
|
+
web 特店代號
|
|
13
|
+
send_time 交易時間,格式 fffssmmHHyyyyMMdd(毫秒在最前面)
|
|
14
|
+
rsamsg 業務參數 → urlencode → RSA 分段加密 → base64
|
|
15
|
+
check_value 業務參數 → ASCII 排序 → urlencode → 尾接 SHA2 密鑰 → SHA256
|
|
16
|
+
|
|
17
|
+
API 文件: 參見 references/sunpay-payment-api.md
|
|
18
|
+
|
|
19
|
+
依賴:
|
|
20
|
+
pip install requests cryptography
|
|
21
|
+
|
|
22
|
+
直接執行本檔會跑官方測試向量的自我驗證,不會發出任何網路請求:
|
|
23
|
+
python sunpay-payment-example.py
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
import base64
|
|
27
|
+
import hashlib
|
|
28
|
+
import json
|
|
29
|
+
import urllib.parse
|
|
30
|
+
from dataclasses import dataclass
|
|
31
|
+
from datetime import datetime
|
|
32
|
+
from typing import Any, Dict, Optional
|
|
33
|
+
|
|
34
|
+
import requests
|
|
35
|
+
|
|
36
|
+
try:
|
|
37
|
+
from cryptography.hazmat.primitives import serialization
|
|
38
|
+
from cryptography.hazmat.primitives.asymmetric import padding
|
|
39
|
+
except ImportError: # 自我驗證只用到 SHA256,不強制安裝 cryptography
|
|
40
|
+
serialization = None
|
|
41
|
+
padding = None
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
# 加密分段 117 byte、解密分段 128 byte —— 兩者不同,很容易誤寫成同一個值。
|
|
45
|
+
# 128 是 1024-bit RSA 的密文區塊固定長度;117 = 128 - 11,
|
|
46
|
+
# 扣掉的 11 byte 是 PKCS#1 v1.5 的 padding。
|
|
47
|
+
RSA_ENCRYPT_CHUNK = 117
|
|
48
|
+
RSA_DECRYPT_CHUNK = 128
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
# ============================================================================
|
|
52
|
+
# 簽章與加密
|
|
53
|
+
# ============================================================================
|
|
54
|
+
|
|
55
|
+
def build_send_time(now: Optional[datetime] = None) -> str:
|
|
56
|
+
"""組出 send_time。
|
|
57
|
+
|
|
58
|
+
⚠️ 格式是 fffssmmHHyyyyMMdd —— 毫秒在最前面、日期在最後,
|
|
59
|
+
不是一般的 yyyyMMddHHmmssfff。
|
|
60
|
+
⚠️ 超過 120 秒即視為無效交易,主機需做 NTP 校時。
|
|
61
|
+
"""
|
|
62
|
+
n = now or datetime.now()
|
|
63
|
+
return f'{n.microsecond // 1000:03d}{n.second:02d}{n.minute:02d}{n.hour:02d}{n:%Y%m%d}'
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _canonical(payload: Dict[str, Any]) -> str:
|
|
67
|
+
"""依 ASCII 升序排序後序列化,不留空白。
|
|
68
|
+
|
|
69
|
+
⚠️ 手冊在兩處重複警告「請務必將 head 與 body 參數進行 ASCII 排序,
|
|
70
|
+
以免加密失敗」。排序要套用到巢狀的 head 與 body 內部。
|
|
71
|
+
"""
|
|
72
|
+
ordered = {
|
|
73
|
+
k: (dict(sorted(v.items())) if isinstance(v, dict) else v)
|
|
74
|
+
for k, v in sorted(payload.items())
|
|
75
|
+
}
|
|
76
|
+
return json.dumps(ordered, separators=(',', ':'), ensure_ascii=False)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def make_check_value(payload: Dict[str, Any], sha2_key: str) -> str:
|
|
80
|
+
"""產生 check_value。
|
|
81
|
+
|
|
82
|
+
排序 → JSON → urlencode → **尾端直接串上 SHA2 密鑰** → SHA256。
|
|
83
|
+
|
|
84
|
+
⚠️ 密鑰是接在字串尾端,不是 ECPay 那種
|
|
85
|
+
`HashKey=...&參數&HashIV=...` 的前後包夾。
|
|
86
|
+
⚠️ 值為 null 的參數不參與簽名(官方明註),本函式已於 build 階段排除。
|
|
87
|
+
"""
|
|
88
|
+
encoded = urllib.parse.quote(_canonical(payload), safe='')
|
|
89
|
+
return hashlib.sha256((encoded + sha2_key).encode('utf-8')).hexdigest()
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def make_rsamsg(payload: Dict[str, Any], public_key_pem: str) -> str:
|
|
93
|
+
"""產生 rsamsg:urlencode 後以 RSA 分段加密,再 base64。"""
|
|
94
|
+
if serialization is None:
|
|
95
|
+
raise RuntimeError('需要 cryptography 套件:pip install cryptography')
|
|
96
|
+
|
|
97
|
+
key = serialization.load_pem_public_key(public_key_pem.encode('utf-8'))
|
|
98
|
+
data = urllib.parse.quote(_canonical(payload), safe='').encode('utf-8')
|
|
99
|
+
|
|
100
|
+
out = bytearray()
|
|
101
|
+
for i in range(0, len(data), RSA_ENCRYPT_CHUNK):
|
|
102
|
+
out += key.encrypt(data[i:i + RSA_ENCRYPT_CHUNK], padding.PKCS1v15())
|
|
103
|
+
return base64.b64encode(bytes(out)).decode('ascii')
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def parse_rsamsg(rsamsg: str, private_key_pem: str) -> Dict[str, Any]:
|
|
107
|
+
"""解密紅陽回傳的 rsamsg。
|
|
108
|
+
|
|
109
|
+
⚠️ 解密分段是 128 byte,不是加密時的 117。
|
|
110
|
+
"""
|
|
111
|
+
if serialization is None:
|
|
112
|
+
raise RuntimeError('需要 cryptography 套件:pip install cryptography')
|
|
113
|
+
|
|
114
|
+
key = serialization.load_pem_private_key(private_key_pem.encode('utf-8'), password=None)
|
|
115
|
+
raw = base64.b64decode(rsamsg)
|
|
116
|
+
|
|
117
|
+
out = bytearray()
|
|
118
|
+
for i in range(0, len(raw), RSA_DECRYPT_CHUNK):
|
|
119
|
+
out += key.decrypt(raw[i:i + RSA_DECRYPT_CHUNK], padding.PKCS1v15())
|
|
120
|
+
return json.loads(urllib.parse.unquote(out.decode('utf-8')))
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
# ============================================================================
|
|
124
|
+
# Client
|
|
125
|
+
# ============================================================================
|
|
126
|
+
|
|
127
|
+
TRADE_URL = 'https://trade.sunpay.com.tw/v4/cash'
|
|
128
|
+
TEST_TRADE_URL = 'https://testtrade.sunpay.com.tw/v4/cash'
|
|
129
|
+
QUERY_URL = 'https://trade.sunpay.com.tw/v4/query/PaymentCheck'
|
|
130
|
+
# 注意:交易與查詢是 /v4/,請款與退款仍是 /v3/ —— 同一份手冊裡版號不一致
|
|
131
|
+
REFUND_URL = 'https://trade.sunpay.com.tw/v3/Service/CardRefund'
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@dataclass
|
|
135
|
+
class SunpayConfig:
|
|
136
|
+
web: str # 特店代號
|
|
137
|
+
public_key_pem: str # 紅陽提供的 RSA 公鑰
|
|
138
|
+
sha2_key: str # 紅陽提供的 SHA2 密鑰
|
|
139
|
+
sandbox: bool = True
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class SunpayClient:
|
|
143
|
+
def __init__(self, config: SunpayConfig, timeout: int = 15):
|
|
144
|
+
self.config = config
|
|
145
|
+
self.timeout = timeout
|
|
146
|
+
|
|
147
|
+
def build_form(self, body: Dict[str, Any]) -> Dict[str, str]:
|
|
148
|
+
"""組出要 POST 的四個欄位。回傳 dict,可直接餵給 requests 的 data。"""
|
|
149
|
+
send_time = build_send_time()
|
|
150
|
+
payload = {
|
|
151
|
+
'head': {'send_time': send_time, 'web': self.config.web},
|
|
152
|
+
# null 不參與簽名,先濾掉
|
|
153
|
+
'body': {k: v for k, v in body.items() if v is not None},
|
|
154
|
+
}
|
|
155
|
+
return {
|
|
156
|
+
'web': self.config.web,
|
|
157
|
+
'send_time': send_time,
|
|
158
|
+
'rsamsg': make_rsamsg(payload, self.config.public_key_pem),
|
|
159
|
+
'check_value': make_check_value(payload, self.config.sha2_key),
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
def create_payment(
|
|
163
|
+
self,
|
|
164
|
+
td: str,
|
|
165
|
+
mn: int,
|
|
166
|
+
*,
|
|
167
|
+
card_type: Optional[str] = None,
|
|
168
|
+
order_info: Optional[str] = None,
|
|
169
|
+
email: Optional[str] = None,
|
|
170
|
+
note1: Optional[str] = None,
|
|
171
|
+
) -> requests.Response:
|
|
172
|
+
"""建立交易。回傳的是要導轉給消費者的頁面。
|
|
173
|
+
|
|
174
|
+
card_type:01 信用卡 / 02 銀聯 / 03 ApplePay 或 GooglePay /
|
|
175
|
+
06 超商代碼 / 07 超商條碼 / 08 虛擬帳號 /
|
|
176
|
+
09 超商取貨付款 / 10 街口支付
|
|
177
|
+
不帶則由消費者在紅陽收銀台自行選擇。
|
|
178
|
+
|
|
179
|
+
⚠️ mn 必須是正整數,不可有小數點或千位符號。
|
|
180
|
+
"""
|
|
181
|
+
form = self.build_form({
|
|
182
|
+
'td': td,
|
|
183
|
+
'mn': str(mn),
|
|
184
|
+
'card_type': card_type,
|
|
185
|
+
'order_info': order_info,
|
|
186
|
+
'email': email,
|
|
187
|
+
'note1': note1,
|
|
188
|
+
})
|
|
189
|
+
url = TEST_TRADE_URL if self.config.sandbox else TRADE_URL
|
|
190
|
+
return requests.post(url, data=form, timeout=self.timeout)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
# ============================================================================
|
|
194
|
+
# 回應處理
|
|
195
|
+
# ============================================================================
|
|
196
|
+
|
|
197
|
+
# ⚠️ 同一個欄位名 pay_result,在兩支 API 的語意不同 ——
|
|
198
|
+
# 12 在交易通知是「已建立」,在查詢 API 卻是「查無該筆訂單」。
|
|
199
|
+
# 因此兩張表必須分開維護,絕不可共用同一份 mapping。
|
|
200
|
+
|
|
201
|
+
CALLBACK_RESULT = {
|
|
202
|
+
'10': '交易成功',
|
|
203
|
+
'11': '交易失敗',
|
|
204
|
+
'12': '已建立', # ← 與查詢 API 的 12 意義不同
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
QUERY_RESULT = {
|
|
208
|
+
'06': '交易編號或訂單編號須擇一',
|
|
209
|
+
'10': '交易成功',
|
|
210
|
+
'11': '交易失敗',
|
|
211
|
+
'12': '查無該筆訂單', # ← 與交易通知的 12 意義不同
|
|
212
|
+
'13': '交易未完成',
|
|
213
|
+
'14': '訂單退款',
|
|
214
|
+
'15': '交易取消',
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def describe_callback(pay_result: str) -> str:
|
|
219
|
+
return CALLBACK_RESULT.get(pay_result, f'未知代碼 {pay_result}')
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def describe_query(pay_result: str) -> str:
|
|
223
|
+
return QUERY_RESULT.get(pay_result, f'未知代碼 {pay_result}')
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def parse_logistics_notify(form: Dict[str, str]) -> Dict[str, str]:
|
|
227
|
+
"""解析物流狀態通知。
|
|
228
|
+
|
|
229
|
+
⚠️ 與交易 CallBack 的格式不同:這支是 HTTP FORM POST key-value
|
|
230
|
+
(非 JSON),且**所有欄位都經過 URL Encode**,需先解碼(UTF-8)。
|
|
231
|
+
⚠️ 訂單編號欄位是大寫的 Td,與請求端的小寫 td 不同。
|
|
232
|
+
"""
|
|
233
|
+
return {k: urllib.parse.unquote_plus(v) for k, v in form.items()}
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
# ============================================================================
|
|
237
|
+
# 自我驗證(官方測試向量)
|
|
238
|
+
# ============================================================================
|
|
239
|
+
|
|
240
|
+
def _self_test() -> int:
|
|
241
|
+
"""用紅陽金流手冊 v1.1.0 的測試向量驗證 check_value 實作。
|
|
242
|
+
|
|
243
|
+
同時驗證我們自行組出的 urlencode 字串與手冊逐字相同 ——
|
|
244
|
+
這是最容易出錯的一步(排序、空白、safe 字元集)。
|
|
245
|
+
"""
|
|
246
|
+
sha2_key = 'D2AE96E5528531CFCDE90591695F973D23846ABD01A639AB1D3E0322D56E0ED9'
|
|
247
|
+
expected_encoded = (
|
|
248
|
+
'%7B%22body%22%3A%7B%22country_type%22%3A%22cht%22%2C%22mn%22%3A%22200%22%2C'
|
|
249
|
+
'%22td%22%3A%22TT1695802894%22%7D%2C%22head%22%3A%7B%22send_time%22%3A'
|
|
250
|
+
'%2258534211620230927%22%2C%22web%22%3A%22MC31793850%22%7D%7D'
|
|
251
|
+
)
|
|
252
|
+
expected_check = '3df3acb3c4c3de1cb352a31bea3df6341e7c24b53aec8c695c32e3aa417cad26'
|
|
253
|
+
|
|
254
|
+
payload = {
|
|
255
|
+
'body': {'country_type': 'cht', 'mn': '200', 'td': 'TT1695802894'},
|
|
256
|
+
'head': {'send_time': '58534211620230927', 'web': 'MC31793850'},
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
failed = 0
|
|
260
|
+
print('紅陽官方測試向量驗證')
|
|
261
|
+
|
|
262
|
+
encoded = urllib.parse.quote(_canonical(payload), safe='')
|
|
263
|
+
ok = encoded == expected_encoded
|
|
264
|
+
failed += not ok
|
|
265
|
+
print(f' [{"PASS" if ok else "FAIL"}] urlencode 結果與手冊逐字相同')
|
|
266
|
+
if not ok:
|
|
267
|
+
print(f' 期望 {expected_encoded[:60]}...')
|
|
268
|
+
print(f' 實得 {encoded[:60]}...')
|
|
269
|
+
|
|
270
|
+
got = make_check_value(payload, sha2_key)
|
|
271
|
+
ok = got == expected_check
|
|
272
|
+
failed += not ok
|
|
273
|
+
print(f' [{"PASS" if ok else "FAIL"}] check_value')
|
|
274
|
+
if not ok:
|
|
275
|
+
print(f' 期望 {expected_check}')
|
|
276
|
+
print(f' 實得 {got}')
|
|
277
|
+
|
|
278
|
+
# send_time 格式:毫秒在最前面、日期在最後
|
|
279
|
+
st = build_send_time(datetime(2023, 9, 27, 16, 21, 34, 585_000))
|
|
280
|
+
ok = st == '585342116' + '20230927'
|
|
281
|
+
failed += not ok
|
|
282
|
+
print(f' [{"PASS" if ok else "FAIL"}] send_time 格式 fffssmmHHyyyyMMdd(實得 {st})')
|
|
283
|
+
|
|
284
|
+
# 兩張代碼表的 12 必須不同義
|
|
285
|
+
ok = describe_callback('12') != describe_query('12')
|
|
286
|
+
failed += not ok
|
|
287
|
+
print(f' [{"PASS" if ok else "FAIL"}] pay_result=12 在交易通知與查詢 API 語意不同'
|
|
288
|
+
f'({describe_callback("12")} vs {describe_query("12")})')
|
|
289
|
+
|
|
290
|
+
print()
|
|
291
|
+
print('全部通過' if failed == 0 else f'{failed} 項失敗')
|
|
292
|
+
return 1 if failed else 0
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
if __name__ == '__main__':
|
|
296
|
+
raise SystemExit(_self_test())
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> 官方開放文件: https://open-doc.jkos.com/
|
|
4
4
|
> 公司: 街口電子支付股份有限公司(專營電子支付機構)
|
|
5
5
|
> Captured: 2026-08-08 · doc_access: **public**(文件站免登入)
|
|
6
|
-
> Status:
|
|
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
|
-
|
|
|
276
|
-
|
|
277
|
-
|
|
|
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
|
-
|
|
|
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
|
-
##
|
|
726
|
+
## 13. 來源
|
|
585
727
|
|
|
586
728
|
- 街口開放文件 — https://open-doc.jkos.com/
|
|
587
729
|
- 線上支付 OnlinePay — https://open-doc.jkos.com/?docs=線上支付onlinepay
|
|
@@ -48,8 +48,10 @@ CSV_CONFIG = {
|
|
|
48
48
|
},
|
|
49
49
|
'field': {
|
|
50
50
|
'file': 'field-mappings.csv',
|
|
51
|
-
|
|
52
|
-
|
|
51
|
+
# 逐一列出所有 provider 欄位 —— 原本只涵蓋 3 家,
|
|
52
|
+
# 導致搜尋其餘 provider 的欄位名時完全比對不到
|
|
53
|
+
'search_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'smilepay_name', 'pchomepay_name', 'ezpay_name', 'paynow_name', 'shopline_name', 'linepay_name', 'tappay_name', 'opay_name', 'jkopay_name', 'sunpay_name', 'gomypay_name', 'notes'],
|
|
54
|
+
'output_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'smilepay_name', 'pchomepay_name', 'ezpay_name', 'paynow_name', 'shopline_name', 'linepay_name', 'tappay_name', 'opay_name', 'jkopay_name', 'sunpay_name', 'gomypay_name', 'type', 'required', 'notes']
|
|
53
55
|
},
|
|
54
56
|
'payment_method': {
|
|
55
57
|
'file': 'payment-methods.csv',
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
|
-
"platform": "
|
|
3
|
-
"displayName": "
|
|
2
|
+
"platform": "cline",
|
|
3
|
+
"displayName": "Cline",
|
|
4
4
|
"installType": "full",
|
|
5
5
|
"folderStructure": {
|
|
6
|
-
"root": ".
|
|
7
|
-
"skillPath": "
|
|
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": {
|
package/dist/index.js
CHANGED
|
@@ -15824,7 +15824,7 @@ var AI_TYPES = [
|
|
|
15824
15824
|
"kiro",
|
|
15825
15825
|
"codex",
|
|
15826
15826
|
"qoder",
|
|
15827
|
-
"
|
|
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
|
-
|
|
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, ".
|
|
15994
|
-
detected.push("
|
|
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/
|
|
16030
|
+
return "GitHub Copilot (.github/skills/)";
|
|
16031
16031
|
case "kiro":
|
|
16032
|
-
return "Kiro (.kiro/
|
|
16032
|
+
return "Kiro (.kiro/skills/)";
|
|
16033
16033
|
case "codex":
|
|
16034
16034
|
return "Codex CLI (.codex/skills/)";
|
|
16035
16035
|
case "qoder":
|
|
16036
|
-
return "Qoder (.qoder/
|
|
16037
|
-
case "
|
|
16038
|
-
return "
|
|
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: "
|
|
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.
|
|
3
|
+
"version": "1.5.0",
|
|
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",
|