taiwan-payment-skill 1.2.0 → 1.3.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 +8 -4
- package/assets/taiwan-payment/CLAUDE.md +4 -1
- package/assets/taiwan-payment/EXAMPLES.md +48 -0
- package/assets/taiwan-payment/README.md +23 -7
- package/assets/taiwan-payment/SKILL.md +29 -2
- package/assets/taiwan-payment/data/error-codes.csv +60 -32
- package/assets/taiwan-payment/data/operations.csv +9 -0
- package/assets/taiwan-payment/data/providers.csv +3 -0
- package/assets/taiwan-payment/examples/ezpay-payment-example.py +690 -690
- package/assets/taiwan-payment/examples/linepay-payment-example.py +305 -0
- package/assets/taiwan-payment/examples/paynow-payment-example.py +767 -767
- package/assets/taiwan-payment/examples/pchomepay-payment-example.py +556 -556
- package/assets/taiwan-payment/examples/shopline-payment-example.py +291 -0
- package/assets/taiwan-payment/examples/smilepay-payment-example.py +673 -673
- package/assets/taiwan-payment/examples/tappay-payment-example.py +337 -0
- package/assets/taiwan-payment/references/ezpay-payment-api.md +660 -660
- package/assets/taiwan-payment/references/linepay-payment-api.md +940 -0
- package/assets/taiwan-payment/references/paynow-payment-api.md +1654 -1654
- package/assets/taiwan-payment/references/pchomepay-payment-api.md +1431 -1431
- package/assets/taiwan-payment/references/shopline-payment-api.md +1523 -0
- package/assets/taiwan-payment/references/smilepay-payment-api.md +919 -919
- package/assets/taiwan-payment/references/tappay-payment-api.md +1245 -0
- package/assets/templates/base/skill-content.md +27 -0
- package/assets/templates/platforms/agent.json +2 -2
- package/assets/templates/platforms/antigravity.json +1 -1
- package/assets/templates/platforms/claude.json +2 -2
- package/assets/templates/platforms/codebuddy.json +2 -2
- package/assets/templates/platforms/codex.json +2 -2
- package/assets/templates/platforms/continue.json +2 -2
- package/assets/templates/platforms/copilot.json +2 -2
- package/assets/templates/platforms/cursor.json +2 -2
- package/assets/templates/platforms/gemini.json +2 -2
- package/assets/templates/platforms/kiro.json +2 -2
- package/assets/templates/platforms/opencode.json +2 -2
- package/assets/templates/platforms/qoder.json +2 -2
- package/assets/templates/platforms/roocode.json +2 -2
- package/assets/templates/platforms/trae.json +2 -2
- package/assets/templates/platforms/windsurf.json +2 -2
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<h3 align="center">台灣金流 AI 開發技能包</h3>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi
|
|
6
|
+
<strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi 統一 · SmilePay 速買配 · PChomePay 拍錢包 · ezPay 簡單付 · PayNow 立吉富</strong>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
@@ -118,6 +118,10 @@ taiwan-payment init --ai antigravity --global # ~/.gemini/antigravity/global_sk
|
|
|
118
118
|
| **ECPay 綠界** | URL Encode + SHA256 | Form POST | 市佔率最高,穩定性佳 |
|
|
119
119
|
| **NewebPay 藍新** | AES-256-CBC + SHA256 | Form POST + AES | 支援最多支付方式 (13 種) |
|
|
120
120
|
| **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON | RESTful 設計,API 現代化 |
|
|
121
|
+
| **SmilePay 速買配** | Verify_key + Mid_smilepay 加權檢核碼 | Form POST + XML 回應 | 老牌、簡單、無 AES 加密門檻 |
|
|
122
|
+
| **PChomePay 拍錢包** | HTTP Basic Auth → pcpay-token | RESTful JSON | PChome 生態、5% P 幣回饋、自帶超商取貨物流 |
|
|
123
|
+
| **ezPay 簡單付** | 同 NewebPay (AES-256-CBC + SHA256) | Form POST + AES | 藍新小型商家品牌,跨境支付寶/微信 |
|
|
124
|
+
| **PayNow 立吉富** | JWT Bearer (現代) / 動態 AES-256 (傳統) | RESTful JSON / Form POST | 雙 API 並行,Apple Pay 完整支援(含延遲扣款) |
|
|
121
125
|
|
|
122
126
|
---
|
|
123
127
|
|
|
@@ -178,10 +182,10 @@ python scripts/test_payment.py all
|
|
|
178
182
|
- 完整 API 文檔 (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow)
|
|
179
183
|
- BM25 搜索引擎
|
|
180
184
|
- 智能推薦系統
|
|
181
|
-
-
|
|
185
|
+
- 7 個 Python 範例(每家服務商一個)
|
|
182
186
|
- 7 個 CSV 數據檔 (易於維護)
|
|
183
|
-
- 加密實作指南 (SHA256, AES-CBC, AES-GCM)
|
|
184
|
-
- 16 個疑難排解案例
|
|
187
|
+
- 加密實作指南 (SHA256, AES-128-CBC, AES-256-CBC, AES-256-GCM, JWT, 動態 AES, Basic Auth → Token)
|
|
188
|
+
- 16+ 個疑難排解案例
|
|
185
189
|
|
|
186
190
|
---
|
|
187
191
|
|
|
@@ -36,7 +36,10 @@ taiwan-payment/ # Source of Truth
|
|
|
36
36
|
│ ├── smilepay-payment-api.md
|
|
37
37
|
│ ├── pchomepay-payment-api.md
|
|
38
38
|
│ ├── ezpay-payment-api.md
|
|
39
|
-
│
|
|
39
|
+
│ ├── paynow-payment-api.md
|
|
40
|
+
│ ├── shopline-payment-api.md
|
|
41
|
+
│ ├── linepay-payment-api.md
|
|
42
|
+
│ └── tappay-payment-api.md
|
|
40
43
|
├── scripts/ # Utility scripts
|
|
41
44
|
│ ├── core.py # BM25 search engine
|
|
42
45
|
│ ├── recommend.py # Recommendation system
|
|
@@ -1491,4 +1491,52 @@ PayNow 有**兩代 API 並行**:
|
|
|
1491
1491
|
|
|
1492
1492
|
---
|
|
1493
1493
|
|
|
1494
|
+
## Shopline Payments 範例
|
|
1495
|
+
|
|
1496
|
+
Shopline Payments (SLP) 採 **HTTP Header `merchantId` + `apiKey`** 認證,所有金額以**分**為單位(NT$1000 = 100000)。提供 Redirect 與 Embedded SDK 雙模式,Webhook 用 HMAC-SHA256 驗章。
|
|
1497
|
+
|
|
1498
|
+
### 完整 Python 範例
|
|
1499
|
+
請見 [`examples/shopline-payment-example.py`](examples/shopline-payment-example.py) — 涵蓋 sessions/create / sessionQuery / refund / Webhook 驗章。
|
|
1500
|
+
|
|
1501
|
+
### 三大要點
|
|
1502
|
+
|
|
1503
|
+
1. **金額是分(cents)**:NT$1,050 要傳 `value: 105000`,弄錯會差 100 倍。
|
|
1504
|
+
2. **僅支援 TWD**:`currency` 固定為 `TWD`;其他幣別不支援。
|
|
1505
|
+
3. **Webhook 驗章**:`x-slp-signature: sha256=<hex>` header,HMAC-SHA256 用 `webhookSecret` 對 raw body 簽。**用 raw bytes,不要 parse JSON 後再 stringify**(會差換行/空白)。
|
|
1506
|
+
|
|
1507
|
+
---
|
|
1508
|
+
|
|
1509
|
+
## LINE Pay v4 範例
|
|
1510
|
+
|
|
1511
|
+
LINE Pay 採 **兩段式流程**:`Request → Confirm`。每次請求需產生 Nonce + HMAC-SHA256 簽章。
|
|
1512
|
+
|
|
1513
|
+
### 完整 Python 範例
|
|
1514
|
+
請見 [`examples/linepay-payment-example.py`](examples/linepay-payment-example.py) — 涵蓋 Request / Confirm / Capture / Void / Refund / Preapproved Pay (自動扣款)。
|
|
1515
|
+
|
|
1516
|
+
### 五大要點
|
|
1517
|
+
|
|
1518
|
+
1. **HMAC string-to-sign 公式(v3 慣例)**:`ChannelSecret + ApiPath + Body + Nonce` (POST) / `ChannelSecret + ApiPath + QueryString + Nonce` (GET)。⚠️ v4 公式與 v3 是否完全一致需以官方 PDF 驗證。
|
|
1519
|
+
2. **transactionId 是 19 位數字**:在 JS 直接用 number 會被 IEEE-754 截斷,**永遠用字串處理**。
|
|
1520
|
+
3. **Confirm 的 amount/currency 必須與 Request 完全一致**:差一塊錢就 1183 錯誤。
|
|
1521
|
+
4. **Capture 兩階段授權**:建立時 `options.payment.capture=false` 只授權;之後手動呼叫 `/capture` 請款,可分批請款多次。
|
|
1522
|
+
5. **Preapproved Pay 自動扣款**:建立時帶 `payType=PREAPPROVED` 取得 `regKey`,之後用 `/preapprovedPay/{regKey}/payment` 直接扣款,免使用者再次確認。
|
|
1523
|
+
|
|
1524
|
+
---
|
|
1525
|
+
|
|
1526
|
+
## TapPay 範例
|
|
1527
|
+
|
|
1528
|
+
TapPay 是 **PCI 隔離設計**:前端 SDK 取 Prime(60 秒 TTL)→ 後端用 Prime 呼叫 pay-by-prime。商家從不接觸卡號。
|
|
1529
|
+
|
|
1530
|
+
### 完整 Python 範例
|
|
1531
|
+
請見 [`examples/tappay-payment-example.py`](examples/tappay-payment-example.py) — 涵蓋 pay-by-prime / pay-by-card-token (重複扣款) / refund / query / remove-card。
|
|
1532
|
+
|
|
1533
|
+
### 四大要點
|
|
1534
|
+
|
|
1535
|
+
1. **三段式金鑰**:`Partner Key` (後端密鑰) / `App Key` (前端 SDK 公鑰) / `Merchant ID`。**Partner Key 絕對不可放前端**。
|
|
1536
|
+
2. **Prime 是 60 秒一次性 token**:前端取 Prime 後要立刻送後端付款;過期或重用會 status=3。
|
|
1537
|
+
3. **重複扣款**:`pay-by-prime` 帶 `remember=true` 後,回應內 `card_secret` 含 `card_key + card_token`,存起來下次直接 `pay-by-card-token`,免再過 SDK。適合訂閱與快速結帳。
|
|
1538
|
+
4. **status=0 才是成功**:別只看 HTTP 200;TapPay HTTP 200 但 status≠0 是業務失敗。
|
|
1539
|
+
|
|
1540
|
+
---
|
|
1541
|
+
|
|
1494
1542
|
**更多範例持續更新中...**
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<h3 align="center">台灣金流 AI 開發技能包</h3>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi
|
|
6
|
+
<strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi 統一 · SmilePay 速買配 · PChomePay 拍錢包 · ezPay 簡單付 · PayNow 立吉富</strong>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
@@ -22,10 +22,12 @@
|
|
|
22
22
|
|
|
23
23
|
## 專案簡介
|
|
24
24
|
|
|
25
|
-
Taiwan Payment Skill 是專為台灣金流整合設計的 AI
|
|
25
|
+
Taiwan Payment Skill 是專為台灣金流整合設計的 AI 開發工具包,支援十大金流平台(ECPay 綠界、NewebPay 藍新、PAYUNi 統一、SmilePay 速買配、PChomePay 拍錢包、ezPay 簡單付、PayNow 立吉富)的完整 API 整合。本工具包提供企業級程式碼範例、BM25 智能搜尋引擎、服務商推薦系統與代碼生成器,協助開發團隊快速完成金流系統整合。
|
|
26
26
|
|
|
27
|
-
**版本:** 1.
|
|
27
|
+
**版本:** 1.3.0
|
|
28
28
|
**狀態:** Production Ready
|
|
29
|
+
**v1.3.0 新增:** Shopline Payments / LINE Pay v4 / TapPay 3 家金流服務商完整支援
|
|
30
|
+
**v1.2.0:** SmilePay / PChomePay / ezPay / PayNow 4 家金流服務商完整支援
|
|
29
31
|
|
|
30
32
|
---
|
|
31
33
|
|
|
@@ -40,13 +42,20 @@ Taiwan Payment Skill 是專為台灣金流整合設計的 AI 開發工具包,
|
|
|
40
42
|
- **嚴謹錯誤處理** - 完整的例外處理與中文錯誤訊息
|
|
41
43
|
- **實戰測試憑證** - 包含測試環境憑證,可直接執行驗證
|
|
42
44
|
|
|
43
|
-
### 生產級 Python 範例 (
|
|
45
|
+
### 生產級 Python 範例 (10 個)
|
|
44
46
|
|
|
45
47
|
完整的金流整合實作,支援多種付款方式:
|
|
46
48
|
|
|
47
|
-
- **ecpay-payment-example.py** - ECPay
|
|
48
|
-
- **newebpay-payment-example.py** - NewebPay MPG
|
|
49
|
-
- **payuni-payment-example.py** - PAYUNi
|
|
49
|
+
- **ecpay-payment-example.py** - ECPay 金流整合(信用卡 / ATM / 超商代碼 / 超商條碼)
|
|
50
|
+
- **newebpay-payment-example.py** - NewebPay MPG 整合(含 LINE Pay / Apple Pay / Google Pay)
|
|
51
|
+
- **payuni-payment-example.py** - PAYUNi 統一金流(AES-256-GCM、AFTEE、iCash)
|
|
52
|
+
- **smilepay-payment-example.py** - SmilePay 整合(ATM / Barcode / ibon / FamiPort / 聯合信用卡 / 信用卡分期)
|
|
53
|
+
- **pchomepay-payment-example.py** - PChomePay 整合(Basic Auth → pcpay-token 兩階段認證 + 拍錢包 5% P 幣回饋)
|
|
54
|
+
- **ezpay-payment-example.py** - ezPay 簡單付整合(與 NewebPay 共用 MPG 加密;diff 文件)
|
|
55
|
+
- **paynow-payment-example.py** - PayNow 立吉富整合(現代 PaymentIntent + 傳統 cashflow 雙 API)
|
|
56
|
+
- **shopline-payment-example.py** - Shopline Payments 整合(Redirect / Embedded SDK / HMAC-SHA256 Webhook)
|
|
57
|
+
- **linepay-payment-example.py** - LINE Pay v4 整合(Request → Confirm 兩段式 + Capture/Void + Preapproved Pay)
|
|
58
|
+
- **tappay-payment-example.py** - TapPay 整合(Prime 兩段式 / pay-by-card-token 重複扣款 / PCI 隔離)
|
|
50
59
|
|
|
51
60
|
### BM25 智能搜尋引擎
|
|
52
61
|
|
|
@@ -165,6 +174,13 @@ taiwan-payment init --ai claude --global
|
|
|
165
174
|
| **ECPay 綠界** | SHA256 CheckMacValue | Form POST | 信用卡、ATM、超商代碼、超商條碼 |
|
|
166
175
|
| **NewebPay 藍新** | AES-256-CBC + SHA256 | Form POST + AES | 信用卡、ATM、超商、LINE Pay、Apple Pay (13 種) |
|
|
167
176
|
| **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON | 信用卡、ATM、超商、AFTEE、iCash Pay |
|
|
177
|
+
| **SmilePay 速買配** | Verify_key + Mid_smilepay 加權檢核碼 | Form POST + XML 回應 | ATM、Barcode、ibon、FamiPort、信用卡、信用卡分期、聯合信用卡 |
|
|
178
|
+
| **PChomePay 拍錢包** | HTTP Basic Auth → pcpay-token | RESTful JSON | 信用卡(含分期)、ATM 虛擬帳號、超商代碼、拍錢包(5% P 幣回饋)、超商取貨付款 |
|
|
179
|
+
| **ezPay 簡單付** | 同 NewebPay (AES-256-CBC + SHA256) | Form POST + AES | 信用卡、ATM、超商、跨境支付寶/微信(與 NewebPay 同集團) |
|
|
180
|
+
| **PayNow 立吉富** | JWT Bearer (現代) / 動態 AES-256 (傳統) | RESTful JSON / Form POST | 信用卡、ATM、超商代碼、Apple Pay (含延遲扣款)、LINE Pay 線上+線下 |
|
|
181
|
+
| **Shopline Payments** | merchantId + apiKey HTTP Header | RESTful JSON | 信用卡、Apple Pay、LINE Pay、街口、ATM、中租 BNPL(金額以分為單位) |
|
|
182
|
+
| **LINE Pay v4** | Channel ID + ChannelSecret + HMAC-SHA256 Nonce | RESTful JSON | LINE 生態系直連、Request→Confirm 兩段式、Preapproved Pay 自動扣款、跨國 |
|
|
183
|
+
| **TapPay** | Partner Key + App Key + Merchant ID(Prime 兩段式) | RESTful JSON | 信用卡、Apple Pay、Google Pay、LINE Pay、Virtual Account;PCI 隔離設計 |
|
|
168
184
|
|
|
169
185
|
---
|
|
170
186
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: taiwan-payment
|
|
3
|
-
description: Taiwan Payment API integration specialist for ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, and
|
|
3
|
+
description: Taiwan Payment API integration specialist for ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay v4, and TapPay payment gateways. Use when developing payment systems, implementing credit card, ATM, CVS, e-wallet, LINE Pay, Apple Pay, Google Pay, or BNPL payments, or working with Taiwan payment gateway APIs. Handles encryption (SHA256, AES-256-CBC, AES-256-GCM, dynamic AES-256, JWT, HMAC-SHA256, Basic Auth → token, Prime token), API requests, and service provider differences.
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Taiwan Payment Development Skill
|
|
8
8
|
|
|
9
|
-
> 此技能涵蓋台灣金流 API
|
|
9
|
+
> 此技能涵蓋台灣金流 API 整合開發,包含綠界 (ECPay)、藍新 (NewebPay)、統一 (PAYUNi)、速買配 (SmilePay)、拍錢包 (PChomePay)、ezPay 簡單付、立吉富 (PayNow)、SHOPLINE Payments、LINE Pay v4、TapPay 共十家服務商。
|
|
10
10
|
|
|
11
11
|
## 快速導覽
|
|
12
12
|
|
|
@@ -19,6 +19,9 @@ user-invocable: true
|
|
|
19
19
|
- `references/pchomepay-payment-api.md` - 拍錢包 API 規格(含 Basic Auth → Token 兩階段認證)
|
|
20
20
|
- `references/ezpay-payment-api.md` - ezPay 簡單付 API 規格(與藍新 Newebpay 同集團、同加密)
|
|
21
21
|
- `references/paynow-payment-api.md` - 立吉富 API 規格(傳統版 cashflow + 現代版 PaymentIntent 雙 API)
|
|
22
|
+
- `references/shopline-payment-api.md` - Shopline Payments API 規格(Redirect + Embedded SDK 雙模式)
|
|
23
|
+
- `references/linepay-payment-api.md` - LINE Pay v4 API 規格(HMAC-SHA256 + Preapproved Pay)
|
|
24
|
+
- `references/tappay-payment-api.md` - TapPay API 規格(Prime 兩段式 / PCI 隔離 / pay-by-token 重複扣款)
|
|
22
25
|
- [EXAMPLES.md](EXAMPLES.md) - 程式碼範例集
|
|
23
26
|
|
|
24
27
|
### 智能工具
|
|
@@ -114,6 +117,9 @@ python scripts/recommend.py "會員制 定期扣款" --format simple
|
|
|
114
117
|
- **PChomePay**: 拍錢包、PChome、P 幣、Basic Auth、Token、虛擬帳號、超商代碼條碼、物流二合一
|
|
115
118
|
- **ezPay**: 簡單付、藍新小型、低門檻、跨境、智冠、支付寶、微信
|
|
116
119
|
- **PayNow**: 立吉富、Apple Pay、PaymentIntent、Stripe-like、JWT、票券、mPOS、現代+傳統雙 API
|
|
120
|
+
- **Shopline**: SHOPLINE 商店、Redirect、Embedded SDK、街口、中租 BNPL、cents、HMAC-SHA256
|
|
121
|
+
- **LINE Pay**: LINE、自動扣款、Preapproved、Capture、Void、跨國、Channel Secret、Nonce
|
|
122
|
+
- **TapPay**: PCI 隔離、Prime、自製結帳頁、card_secret、CherryTech、Apple Pay、Google Pay
|
|
117
123
|
|
|
118
124
|
**反模式警告:**
|
|
119
125
|
推薦系統會自動提示不建議的場景:
|
|
@@ -124,6 +130,9 @@ python scripts/recommend.py "會員制 定期扣款" --format simple
|
|
|
124
130
|
- PChomePay: 不在 PChome 生態系
|
|
125
131
|
- ezPay: 大型商家、需要分期、需要完整支付方式
|
|
126
132
|
- PayNow: 簡單需求(雙 API 學習成本高)
|
|
133
|
+
- Shopline: 不在 SHOPLINE 商店生態
|
|
134
|
+
- LINE Pay: 主要客戶不用 LINE
|
|
135
|
+
- TapPay: 不想自製結帳頁、無前端能力
|
|
127
136
|
|
|
128
137
|
### 付款測試工具 (test_payment.py)
|
|
129
138
|
|
|
@@ -246,6 +255,24 @@ python scripts/test_payment.py all
|
|
|
246
255
|
- **傳輸**: 傳統用 Form POST;現代用 application/json
|
|
247
256
|
- **特色**: 13 種付款方式(含 LINE Pay 線上線下、Apple Pay v1/v2、Apple Pay Deferred 延遲扣款)、Customer / Card Token 會員記憶、`webhookUrl` 推送回呼。**新專案應優先採用現代版 PaymentIntent**
|
|
248
257
|
|
|
258
|
+
### Shopline Payments 特性
|
|
259
|
+
- **優勢**: SHOPLINE 集團官方金流、RESTful JSON 設計、Redirect + Embedded SDK 雙模式
|
|
260
|
+
- **認證**: HTTP Header 帶 `merchantId` + `apiKey`;Webhook 用 HMAC-SHA256
|
|
261
|
+
- **傳輸**: application/json,金額以**分**為單位 (1 TWD = 100),僅支援 TWD
|
|
262
|
+
- **特色**: Embedded SDK 適合自訂 UI 與 PCI 隔離;Redirect 模式快速上線;6 種主流支付(信用卡/Apple Pay/LINE Pay/街口/ATM/中租 BNPL)
|
|
263
|
+
|
|
264
|
+
### LINE Pay 特性
|
|
265
|
+
- **優勢**: LINE 生態系直連、跨國(TW/JP/TH/TW)、自動扣款(Preapproved Pay)、Capture/Void 雙階段授權
|
|
266
|
+
- **認證**: Channel ID + Channel Secret;每次請求需產生 Nonce 並用 HMAC-SHA256 簽章 (`X-LINE-Authorization`)
|
|
267
|
+
- **傳輸**: RESTful JSON v4 規格
|
|
268
|
+
- **特色**: Request → Confirm 兩段式流程;Capture 可手動請款(autoCapture=false);19 位 transactionId(JS 需用字串避免精度遺失);不支援 Apple Pay / Google Pay(這是 LINE Pay 自身就是支付工具)
|
|
269
|
+
|
|
270
|
+
### TapPay 特性
|
|
271
|
+
- **優勢**: PCI 隔離設計(前端 SDK 取 Prime → 後端付款)、支援多元電子錢包(Apple Pay / Google Pay / LINE Pay / 街口)、適合自製結帳頁
|
|
272
|
+
- **認證**: Partner Key(後端)+ App Key(前端)+ Merchant ID 三段式金鑰;Prime 60 秒過期
|
|
273
|
+
- **傳輸**: RESTful JSON
|
|
274
|
+
- **特色**: 兩段式架構 (Prime → pay-by-prime);`card_secret` 機制可記憶卡片做重複扣款 (pay-by-token);`result_url` 雙網址回調;無自家結帳頁,UI 完全在商家自管
|
|
275
|
+
|
|
249
276
|
## 開發實作步驟
|
|
250
277
|
|
|
251
278
|
### 1. 服務實作架構
|
|
@@ -40,35 +40,63 @@ payuni,API_TIMEOUT,API 請求逾時,API Timeout,system,error,重新交易
|
|
|
40
40
|
payuni,PAYMENT_FAILED,付款失敗,Payment Failed,payment,error,稍後重試或使用其他支付方式
|
|
41
41
|
payuni,INVALID_PAYMENT_TYPE,不支援的支付方式,Unsupported Payment Type,validation,error,使用支援的支付方式
|
|
42
42
|
payuni,JSON_PARSE_ERROR,JSON 解析失敗,JSON Parse Error,system,error,檢查 API 回應格式
|
|
43
|
-
smilepay,1,交易成功,Success,success,info,
|
|
44
|
-
smilepay,-1,參數錯誤,Parameter error,validation,error,檢查必填欄位 Dcvc/Rvg2c/Verify_key
|
|
45
|
-
smilepay,-2,商家驗證失敗,Merchant verification failed,auth,error,確認 Verify_key 與 mid 正確
|
|
46
|
-
smilepay,-3,簽章/檢核碼不正確,Signature mismatch,auth,error,通知時驗證 Mid_smilepay 加權檢核碼
|
|
47
|
-
smilepay,-10,Pay_zg 不支援,Unsupported payment type,validation,error,改用支援的 Pay_zg 值 (1/2/3/4/6/11)
|
|
48
|
-
smilepay,-15,訂單金額異常,Amount invalid,validation,error,Amount 必須為正整數
|
|
49
|
-
smilepay,-20,訂單編號重複,Duplicate Data_id,validation,error,使用唯一 Data_id
|
|
50
|
-
smilepay,-23,逾期訂單/訂單已關閉,Order expired,validation,error,檢查 Deadline_date 設定
|
|
51
|
-
pchomepay,10001,APP ID 或 SECRET 錯誤,Invalid Basic Auth credentials,auth,error,檢查 APP ID 與 SECRET 是否正確 base64 編碼
|
|
52
|
-
pchomepay,10003,Token 已過期,Token expired,auth,error,重新呼叫 POST /v1/token 取得新 token
|
|
53
|
-
pchomepay,10004,Token 不存在,Token not found,auth,error,header 必須帶 pcpay-token
|
|
54
|
-
pchomepay,10005,IP 不在白名單,IP not whitelisted,auth,error,將呼叫端 IP 加入後台白名單
|
|
55
|
-
pchomepay,20001,訂單已存在,Duplicate order_id,validation,error,使用唯一 order_id
|
|
56
|
-
pchomepay,20002,訂單金額錯誤,Invalid amount,validation,error,amount 必須為正整數
|
|
57
|
-
pchomepay,30001,退款金額超過原訂單,Refund exceeds original,refund,error,退款金額 + 退款手續費需小於原訂單
|
|
58
|
-
pchomepay,30002,餘額不足,Insufficient balance,refund,error,商家代收帳戶餘額不足以扣除退款 + 手續費
|
|
59
|
-
pchomepay,40001,卡號驗證失敗,Card validation failed,payment,error,信用卡資料錯誤;於 sandbox 改用測試卡號
|
|
60
|
-
pchomepay,90001,超商取貨建立失敗,CVS COD creation failed,logistics,error,參見 taiwan-logistics 文件確認物流欄位
|
|
61
|
-
ezpay,KEY10001,商店代號錯誤,Invalid MerchantID,auth,error,確認 MerchantID 與後台一致
|
|
62
|
-
ezpay,KEY10002,簽章驗證失敗,TradeSha mismatch,auth,error,SHA256 計算需含 HashKey/HashIV 且大寫
|
|
63
|
-
ezpay,KEY10003,加密資料解密失敗,TradeInfo decrypt failed,auth,error,確認 AES-256-CBC + Hex + PKCS7 與 32-char HashKey 16-char HashIV
|
|
64
|
-
ezpay,MEM10001,商家未啟用該付款方式,Method not enabled,validation,error,於 ezPay 後台啟用該付款方式
|
|
65
|
-
ezpay,MPG10001,訂單編號重複,Duplicate MerchantOrderNo,validation,error,使用唯一訂單編號
|
|
66
|
-
ezpay,VACC10001,虛擬帳號逾期,VACC expired,validation,error,檢查 ExpireDate 設定
|
|
67
|
-
paynow,M001,商家代號錯誤,Invalid Merchant,auth,error,確認商家代號正確
|
|
68
|
-
paynow,A001,加密驗證失敗,Encryption validation failed,auth,error,傳統版檢查 GP/GK 動態金鑰;現代版檢查 JWT Bearer
|
|
69
|
-
paynow,B001,訂單金額錯誤,Invalid Amount,validation,error,確認 amount 為正整數且小於 1,000,000,000,000
|
|
70
|
-
paynow,C001,訂單編號重複,Duplicate paymentNo,validation,error,使用唯一 paymentNo (現代版可省略由系統產生)
|
|
71
|
-
paynow,P001,信用卡授權失敗,Card authorization failed,payment,error,改用其他卡或聯繫銀行
|
|
72
|
-
paynow,Q001,Token 過期,JWT expired,auth,error,重新申請 JWT Bearer Token
|
|
73
|
-
paynow,R001,退款超過原訂單,Refund exceeds original,refund,error,確認可退金額
|
|
74
|
-
paynow,T001,信用卡 token 不存在,Card token not found,payment,error,確認 customer 與 card token 仍有效
|
|
43
|
+
smilepay,1,交易成功,Success,success,info,
|
|
44
|
+
smilepay,-1,參數錯誤,Parameter error,validation,error,檢查必填欄位 Dcvc/Rvg2c/Verify_key
|
|
45
|
+
smilepay,-2,商家驗證失敗,Merchant verification failed,auth,error,確認 Verify_key 與 mid 正確
|
|
46
|
+
smilepay,-3,簽章/檢核碼不正確,Signature mismatch,auth,error,通知時驗證 Mid_smilepay 加權檢核碼
|
|
47
|
+
smilepay,-10,Pay_zg 不支援,Unsupported payment type,validation,error,改用支援的 Pay_zg 值 (1/2/3/4/6/11)
|
|
48
|
+
smilepay,-15,訂單金額異常,Amount invalid,validation,error,Amount 必須為正整數
|
|
49
|
+
smilepay,-20,訂單編號重複,Duplicate Data_id,validation,error,使用唯一 Data_id
|
|
50
|
+
smilepay,-23,逾期訂單/訂單已關閉,Order expired,validation,error,檢查 Deadline_date 設定
|
|
51
|
+
pchomepay,10001,APP ID 或 SECRET 錯誤,Invalid Basic Auth credentials,auth,error,檢查 APP ID 與 SECRET 是否正確 base64 編碼
|
|
52
|
+
pchomepay,10003,Token 已過期,Token expired,auth,error,重新呼叫 POST /v1/token 取得新 token
|
|
53
|
+
pchomepay,10004,Token 不存在,Token not found,auth,error,header 必須帶 pcpay-token
|
|
54
|
+
pchomepay,10005,IP 不在白名單,IP not whitelisted,auth,error,將呼叫端 IP 加入後台白名單
|
|
55
|
+
pchomepay,20001,訂單已存在,Duplicate order_id,validation,error,使用唯一 order_id
|
|
56
|
+
pchomepay,20002,訂單金額錯誤,Invalid amount,validation,error,amount 必須為正整數
|
|
57
|
+
pchomepay,30001,退款金額超過原訂單,Refund exceeds original,refund,error,退款金額 + 退款手續費需小於原訂單
|
|
58
|
+
pchomepay,30002,餘額不足,Insufficient balance,refund,error,商家代收帳戶餘額不足以扣除退款 + 手續費
|
|
59
|
+
pchomepay,40001,卡號驗證失敗,Card validation failed,payment,error,信用卡資料錯誤;於 sandbox 改用測試卡號
|
|
60
|
+
pchomepay,90001,超商取貨建立失敗,CVS COD creation failed,logistics,error,參見 taiwan-logistics 文件確認物流欄位
|
|
61
|
+
ezpay,KEY10001,商店代號錯誤,Invalid MerchantID,auth,error,確認 MerchantID 與後台一致
|
|
62
|
+
ezpay,KEY10002,簽章驗證失敗,TradeSha mismatch,auth,error,SHA256 計算需含 HashKey/HashIV 且大寫
|
|
63
|
+
ezpay,KEY10003,加密資料解密失敗,TradeInfo decrypt failed,auth,error,確認 AES-256-CBC + Hex + PKCS7 與 32-char HashKey 16-char HashIV
|
|
64
|
+
ezpay,MEM10001,商家未啟用該付款方式,Method not enabled,validation,error,於 ezPay 後台啟用該付款方式
|
|
65
|
+
ezpay,MPG10001,訂單編號重複,Duplicate MerchantOrderNo,validation,error,使用唯一訂單編號
|
|
66
|
+
ezpay,VACC10001,虛擬帳號逾期,VACC expired,validation,error,檢查 ExpireDate 設定
|
|
67
|
+
paynow,M001,商家代號錯誤,Invalid Merchant,auth,error,確認商家代號正確
|
|
68
|
+
paynow,A001,加密驗證失敗,Encryption validation failed,auth,error,傳統版檢查 GP/GK 動態金鑰;現代版檢查 JWT Bearer
|
|
69
|
+
paynow,B001,訂單金額錯誤,Invalid Amount,validation,error,確認 amount 為正整數且小於 1,000,000,000,000
|
|
70
|
+
paynow,C001,訂單編號重複,Duplicate paymentNo,validation,error,使用唯一 paymentNo (現代版可省略由系統產生)
|
|
71
|
+
paynow,P001,信用卡授權失敗,Card authorization failed,payment,error,改用其他卡或聯繫銀行
|
|
72
|
+
paynow,Q001,Token 過期,JWT expired,auth,error,重新申請 JWT Bearer Token
|
|
73
|
+
paynow,R001,退款超過原訂單,Refund exceeds original,refund,error,確認可退金額
|
|
74
|
+
paynow,T001,信用卡 token 不存在,Card token not found,payment,error,確認 customer 與 card token 仍有效
|
|
75
|
+
shopline,400,參數錯誤,Bad Request,validation,error,檢查 request body 與必填欄位
|
|
76
|
+
shopline,401,認證失敗,Unauthorized,auth,error,檢查 merchantId / apiKey HTTP header
|
|
77
|
+
shopline,403,沒有權限,Forbidden,auth,error,確認 API 權限與 IP 白名單
|
|
78
|
+
shopline,404,資源不存在,Not Found,resource,error,確認 sessionId / paymentId 正確
|
|
79
|
+
shopline,409,重複請求,Conflict,validation,error,使用唯一 referenceNumber
|
|
80
|
+
shopline,422,驗證失敗,Unprocessable Entity,validation,error,檢查欄位格式與業務規則
|
|
81
|
+
shopline,500,伺服器錯誤,Internal Server Error,server,error,稍後重試;持續出現聯繫 SLP support
|
|
82
|
+
linepay,1101,請求超時,Request Timeout,network,error,重試;通常為網路問題
|
|
83
|
+
linepay,1102,認證失敗,Authentication Failed,auth,error,檢查 ChannelId/ChannelSecret 與 HMAC 簽章
|
|
84
|
+
linepay,1104,商戶尚未上線,Merchant not activated,auth,error,於 LINE Pay Merchant Center 啟用商戶
|
|
85
|
+
linepay,1106,Header 錯誤,Header Error,validation,error,檢查 X-LINE-Authorization 與 Nonce
|
|
86
|
+
linepay,1133,認證資訊過期,Authentication Expired,auth,error,Nonce 不可重複;重新產生
|
|
87
|
+
linepay,1141,無效金額,Invalid Amount,validation,error,amount 必須為正整數
|
|
88
|
+
linepay,1142,無效幣別,Invalid Currency,validation,error,Currency 必須為 TWD/USD 等支援值
|
|
89
|
+
linepay,1170,訂單不存在,Order Not Found,resource,error,確認 transactionId
|
|
90
|
+
linepay,1172,訂單已存在,Duplicate Order,validation,error,使用唯一 orderId
|
|
91
|
+
linepay,1183,無效 Confirm,Invalid Confirm,validation,error,Confirm payload amount/currency 須與 Request 完全相同
|
|
92
|
+
linepay,1198,內部錯誤,Internal Error,server,error,聯繫 LINE Pay 技術支援
|
|
93
|
+
tappay,1,付款失敗,Payment Failure,payment,error,檢查 prime 與卡片是否有效
|
|
94
|
+
tappay,2,參數錯誤,Invalid Parameters,validation,error,檢查 partner_key/merchant_id 與 amount 等必填
|
|
95
|
+
tappay,3,prime 錯誤,Invalid Prime,validation,error,Prime 已使用或過期 (60秒);重新取得
|
|
96
|
+
tappay,4,卡片資訊錯誤,Invalid Card,validation,error,卡號/到期/CVC 不正確
|
|
97
|
+
tappay,5,卡片風控,Card Risk,risk,error,銀行風控拒絕;聯繫卡片發行銀行
|
|
98
|
+
tappay,6,系統錯誤,System Error,server,error,聯繫 TapPay 技術支援
|
|
99
|
+
tappay,7,卡片過期,Card Expired,validation,error,使用未過期卡片
|
|
100
|
+
tappay,10003,Partner Key 錯誤,Invalid Partner Key,auth,error,確認 Partner Key 與環境一致 (sandbox/prod)
|
|
101
|
+
tappay,10005,Merchant ID 錯誤,Invalid Merchant ID,auth,error,確認 Merchant ID 設定
|
|
102
|
+
tappay,88001,卡片驗證失敗,Card Verification Failed,validation,error,3DS 驗證失敗;聯繫銀行
|
|
@@ -12,3 +12,12 @@ withdraw,提領款項,N/A,N/A,N/A,N/A,/v1/withdraw,N/A,N/A,N/A,POST,"amount,bank
|
|
|
12
12
|
checkout,跳轉結帳頁,N/A,N/A,N/A,N/A,N/A,N/A,N/A,/api/v1/payment-intent/{id}/checkout,POST,"paymentMethodType,paymentMethodData",PayNow 現代版 Stripe-like checkout flow
|
|
13
13
|
applepay_session,Apple Pay session,N/A,N/A,N/A,N/A,N/A,N/A,N/A,/api/v1/apple-pay/session,POST,"validationURL,domainName",PayNow 現代版 Apple Pay 商家驗證
|
|
14
14
|
applepay_confirm,Apple Pay 確認,N/A,N/A,N/A,N/A,N/A,N/A,N/A,/api/v1/apple-pay/confirm,POST,"applePayPayload",PayNow 現代版 Apple Pay 付款確認
|
|
15
|
+
session_create,Shopline 建立結帳會話,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"merchantId,amount,currency,returnUrl",Shopline Redirect 模式; endpoint 為 /sessions/create
|
|
16
|
+
session_query,Shopline 查詢會話,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,GET,"sessionId",Shopline; /sessions/{sessionId}
|
|
17
|
+
linepay_request,LINE Pay 建立交易,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"amount,currency,orderId,packages",LINE Pay v4; /v3/payments/request
|
|
18
|
+
linepay_confirm,LINE Pay 確認交易,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"amount,currency,transactionId",LINE Pay; /v3/payments/{transactionId}/confirm
|
|
19
|
+
linepay_capture,LINE Pay 請款,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"amount,currency,transactionId",LINE Pay; /v3/payments/authorizations/{transactionId}/capture (含手動請款)
|
|
20
|
+
linepay_void,LINE Pay 取消授權,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"transactionId",LINE Pay; /v3/payments/authorizations/{transactionId}/void
|
|
21
|
+
linepay_preapproved_pay,LINE Pay 自動扣款,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"amount,currency,orderId,productName",LINE Pay 自動扣款 (Preapproved Pay)
|
|
22
|
+
tappay_pay_by_prime,TapPay Prime 付款,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"prime,partner_key,merchant_id,amount,details,cardholder",TapPay; /tpc/payment/pay-by-prime
|
|
23
|
+
tappay_pay_by_token,TapPay Token 付款,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A,POST,"card_key,card_token,partner_key,merchant_id,amount,details",TapPay 重複扣款; /tpc/payment/pay-by-card-token
|
|
@@ -6,3 +6,6 @@ smilepay,速買配 SmilePay,Verify_key + Mid_smilepay,共享密鑰 + 加權檢
|
|
|
6
6
|
pchomepay,拍錢包 PChomePay,Basic Auth -> pcpay-token,Token 雙階段認證,https://sandbox-api.pchomepay.com.tw,https://api.pchomepay.com.tw,請至後台申請,請至後台申請,,application/json,PChome 生態 | P 幣回饋 | 金物流二合一 | RESTful | notify IP 113.196.231.190,medium,RESTful JSON
|
|
7
7
|
ezpay,ezPay 簡單付,AES-256-CBC + SHA256,同 NewebPay MPG,https://ccore.spgateway.com/MPG/mpg_gateway,https://core.spgateway.com/MPG/mpg_gateway,請至後台申請,請至後台申請,請至後台申請,application/x-www-form-urlencoded,藍新小型商家品牌 | 同 NewebPay 加密 | 跨境 | 智冠系,small,Form POST + AES
|
|
8
8
|
paynow,立吉富 PayNow,JWT Bearer (現代) / 動態 AES-256 (傳統),JWT 或 GP/GK 動態金鑰,https://test.paynow.com.tw/service/etopm.aspx,https://www.paynow.com.tw/service/etopm.aspx,請至後台申請,請至後台申請,請至後台申請,application/json (現代) / x-www-form-urlencoded (傳統),雙 API 並行 | Stripe-like 現代 | Apple Pay 完整 | 票券系統,small,Hybrid (傳統 + 現代)
|
|
9
|
+
shopline,Shopline Payments,merchantId + apiKey HTTP Header,Header 認證 + HMAC-SHA256 Webhook,https://sandbox-payments-api.shoplineapp.com,https://payments-api.shoplineapp.com,請至後台申請,請至後台申請,,application/json,SHOPLINE 集團 | RESTful JSON | 金額以分為單位 | Redirect+SDK 雙模式 | TWD only,medium,RESTful JSON
|
|
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
|
|
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/Virtual Account,medium,RESTful JSON
|