taiwan-payment-skill 1.5.4 → 1.5.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -17
- package/assets/taiwan-payment/CLAUDE.md +26 -20
- package/assets/taiwan-payment/README.md +25 -16
- package/assets/taiwan-payment/SKILL.md +11 -6
- package/assets/taiwan-payment/examples/sunpay-payment-example.py +17 -3
- package/assets/taiwan-payment/references/jkopay-payment-api.md +115 -10
- package/assets/taiwan-payment/references/opay-payment-api.md +28 -4
- package/assets/taiwan-payment/references/sunpay-payment-api.md +55 -11
- package/assets/taiwan-payment/scripts/core.py +2 -2
- package/assets/taiwan-payment/scripts/search.py +4 -2
- package/assets/templates/base/quick-reference.md +2 -3
- package/assets/templates/base/skill-content.md +9 -4
- package/assets/templates/platforms/agent.json +2 -2
- package/assets/templates/platforms/claude.json +2 -2
- package/assets/templates/platforms/cline.json +3 -3
- 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 +3 -3
- package/assets/templates/platforms/cursor.json +2 -2
- package/assets/templates/platforms/gemini.json +2 -2
- package/assets/templates/platforms/kiro.json +3 -3
- package/assets/templates/platforms/opencode.json +2 -2
- package/assets/templates/platforms/qoder.json +2 -2
- package/assets/templates/platforms/trae.json +2 -2
- package/assets/templates/platforms/windsurf.json +2 -2
- package/dist/index.js +26 -28
- package/package.json +2 -2
- package/assets/templates/platforms/antigravity.json +0 -25
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<h3 align="center">台灣金流 AI 開發技能包</h3>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
6
|
+
<strong>14 家金流平台一次串接</strong>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
<p align="center">
|
|
14
14
|
<a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/v/taiwan-payment-skill?style=flat-square&logo=npm" alt="npm version"></a>
|
|
15
15
|
<a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/dm/taiwan-payment-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
|
|
16
|
-
<img src="https://img.shields.io/badge/providers-
|
|
16
|
+
<img src="https://img.shields.io/badge/providers-14-success?style=flat-square" alt="14 Providers">
|
|
17
17
|
<img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
|
|
18
18
|
<a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
|
|
19
19
|
</p>
|
|
@@ -54,7 +54,7 @@ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動
|
|
|
54
54
|
|
|
55
55
|
---
|
|
56
56
|
|
|
57
|
-
##
|
|
57
|
+
## 14 家金流平台
|
|
58
58
|
|
|
59
59
|
| 服務商 | 加密 / 認證 | 特色 |
|
|
60
60
|
|---|---|---|
|
|
@@ -63,13 +63,17 @@ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動
|
|
|
63
63
|
| **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON、AFTEE、iCash |
|
|
64
64
|
| **SmilePay 速買配** | Verify_key + 加權檢核碼 | 無 AES、ibon / FamiPort 直接打單 |
|
|
65
65
|
| **PChomePay 拍錢包** | Basic Auth → 8h pcpay-token | PChome 生態、5% P 幣回饋、金物流二合一 |
|
|
66
|
-
| **ezPay 簡單付** |
|
|
66
|
+
| **ezPay 簡單付** | AES-256-CBC(32-byte padding)+ SHA256 | 電子支付機構;境內 TWQR / ezPay 錢包,跨境支付寶 / 微信 |
|
|
67
67
|
| **PayNow 立吉富** | JWT Bearer (現代) / 動態 AES-256 (傳統) | 雙 API、Stripe-like、Apple Pay 完整 |
|
|
68
68
|
| **Shopline Payments** | merchantId + apiKey | 金額以分為單位、HMAC-SHA256 webhook |
|
|
69
69
|
| **LINE Pay v4** | Channel ID/Secret + HMAC-SHA256 + Nonce | Request→Confirm 兩段、Preapproved Pay |
|
|
70
70
|
| **TapPay** | Partner Key (Header) | PCI 隔離、Prime 兩段式、Card Token |
|
|
71
|
+
| **O'Pay 歐付寶** | SHA256 CheckMacValue(同 ECPay) | 與 ECPay 同源架構、AccountLink 銀行快付、延遲撥款 |
|
|
72
|
+
| **JKOPAY 街口** | api-key Header + HMAC-SHA256 digest | 線上支付 / POS / 授權扣款 |
|
|
73
|
+
| **SunPay 紅陽** | RSA 分段加密 + SHA256 check_value | 金流 + 發票 + 超商代收 |
|
|
74
|
+
| **GoMyPay** | 需申請文件 | 參數規格待補 |
|
|
71
75
|
|
|
72
|
-
|
|
76
|
+
O'Pay、GoMyPay 以外皆附可執行 Python 範例,加解密以官方測試向量驗證;錯誤碼見 `data/error-codes.csv`。
|
|
73
77
|
|
|
74
78
|
## 技能包內容
|
|
75
79
|
|
|
@@ -77,23 +81,28 @@ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動
|
|
|
77
81
|
taiwan-payment/
|
|
78
82
|
├── SKILL.md # AI 技能主文檔
|
|
79
83
|
├── EXAMPLES.md # 實戰範例集
|
|
80
|
-
├── references/ #
|
|
84
|
+
├── references/ # 各服務商 API 規格
|
|
81
85
|
│ ├── ecpay-payment-api.md
|
|
82
86
|
│ ├── newebpay-payment-api.md
|
|
83
87
|
│ ├── payuni-payment-api.md
|
|
84
|
-
│ ├── smilepay-payment-api.md #
|
|
88
|
+
│ ├── smilepay-payment-api.md # Mid_smilepay 加權檢核碼
|
|
85
89
|
│ ├── pchomepay-payment-api.md # 含 8h token 流程
|
|
86
|
-
│ ├── ezpay-payment-api.md #
|
|
90
|
+
│ ├── ezpay-payment-api.md # 電子支付平台 + 跨境(依官方手冊)
|
|
87
91
|
│ ├── paynow-payment-api.md # 雙 API 並行
|
|
88
92
|
│ ├── shopline-payment-api.md # Redirect + Embedded
|
|
89
93
|
│ ├── linepay-payment-api.md # HMAC + Preapproved
|
|
90
|
-
│
|
|
91
|
-
├──
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
94
|
+
│ ├── tappay-payment-api.md # Prime + Token 重複扣款
|
|
95
|
+
│ ├── opay-payment-api.md
|
|
96
|
+
│ ├── jkopay-payment-api.md
|
|
97
|
+
│ ├── sunpay-payment-api.md
|
|
98
|
+
│ ├── gomypay-payment-api.md
|
|
99
|
+
│ └── twqr-ewallet-landscape.md # 電子支付/TWQR 生態
|
|
100
|
+
├── examples/ # 可執行 Python 範例
|
|
101
|
+
└── data/ # search / recommend 使用的 CSV
|
|
102
|
+
├── providers.csv
|
|
103
|
+
├── operations.csv
|
|
104
|
+
├── payment-methods.csv
|
|
105
|
+
├── error-codes.csv # 各家官方錯誤碼
|
|
97
106
|
└── ...
|
|
98
107
|
```
|
|
99
108
|
|
|
@@ -115,8 +124,8 @@ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Co
|
|
|
115
124
|
|
|
116
125
|
本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
|
|
117
126
|
|
|
118
|
-
- [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) —
|
|
119
|
-
- [taiwan-logistics-skill](https://www.npmjs.com/package/taiwan-logistics-skill) — 7
|
|
127
|
+
- [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 7 家電子發票加值中心 + 財政部大平台查詢
|
|
128
|
+
- [taiwan-logistics-skill](https://www.npmjs.com/package/taiwan-logistics-skill) — 7 家物流 aggregator + HCT 直連 + 3 家即時配送
|
|
120
129
|
|
|
121
130
|
## 授權
|
|
122
131
|
|
|
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|
|
4
4
|
|
|
5
5
|
## Project Overview
|
|
6
6
|
|
|
7
|
-
Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for
|
|
7
|
+
Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for Taiwan payment platforms (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
|
|
8
8
|
|
|
9
9
|
## Available Scripts
|
|
10
10
|
|
|
@@ -41,22 +41,28 @@ taiwan-payment/ # Source of Truth
|
|
|
41
41
|
│ ├── paynow-payment-api.md
|
|
42
42
|
│ ├── shopline-payment-api.md
|
|
43
43
|
│ ├── linepay-payment-api.md
|
|
44
|
-
│
|
|
44
|
+
│ ├── tappay-payment-api.md
|
|
45
|
+
│ ├── opay-payment-api.md
|
|
46
|
+
│ ├── jkopay-payment-api.md
|
|
47
|
+
│ ├── sunpay-payment-api.md
|
|
48
|
+
│ ├── gomypay-payment-api.md
|
|
49
|
+
│ └── twqr-ewallet-landscape.md
|
|
45
50
|
├── scripts/ # Utility scripts
|
|
46
51
|
│ ├── core.py # BM25 search engine
|
|
47
52
|
│ ├── recommend.py # Recommendation system
|
|
48
|
-
│ ├── search.py # Search CLI
|
|
49
|
-
│ └── test_payment.py #
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
├──
|
|
53
|
-
├──
|
|
54
|
-
├──
|
|
55
|
-
├──
|
|
56
|
-
├──
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
53
|
+
│ ├── search.py # Search CLI
|
|
54
|
+
│ └── test_payment.py # 已知答案測試 + 測試環境連線
|
|
55
|
+
├── examples/ # 可執行範例(CI 以官方測試向量驗證)
|
|
56
|
+
└── data/ # search / recommend 使用的 CSV
|
|
57
|
+
├── providers.csv # 14 家(含 doc_access 文件公開程度分級)
|
|
58
|
+
├── operations.csv
|
|
59
|
+
├── error-codes.csv # 依各家官方文件重建
|
|
60
|
+
├── field-mappings.csv
|
|
61
|
+
├── payment-methods.csv
|
|
62
|
+
├── reasoning.csv
|
|
63
|
+
└── troubleshooting.csv
|
|
64
|
+
|
|
65
|
+
payment-cli/ # CLI installer (taiwan-payment-skill on npm)
|
|
60
66
|
├── src/
|
|
61
67
|
│ ├── commands/init.ts # Install command with template generation
|
|
62
68
|
│ ├── utils/template.ts # Template rendering engine
|
|
@@ -84,7 +90,7 @@ When modifying files:
|
|
|
84
90
|
- `scripts/*.py` - Utility scripts
|
|
85
91
|
- `data/*.csv` - Data files
|
|
86
92
|
|
|
87
|
-
2. **Templates** - Edit in `cli/assets/templates/`:
|
|
93
|
+
2. **Templates** - Edit in `payment-cli/assets/templates/`:
|
|
88
94
|
- `base/skill-content.md` - Common skill content
|
|
89
95
|
- `base/quick-reference.md` - Quick reference (Claude only)
|
|
90
96
|
- `platforms/*.json` - Platform-specific configs (14 platforms)
|
|
@@ -220,7 +226,7 @@ All core logic is in CSV files:
|
|
|
220
226
|
- **error-codes.csv** - Error code lookup table
|
|
221
227
|
- **field-mappings.csv** - Field name mappings across providers
|
|
222
228
|
- **payment-methods.csv** - Payment method details
|
|
223
|
-
- **reasoning.csv** - Recommendation rules
|
|
229
|
+
- **reasoning.csv** - Recommendation rules
|
|
224
230
|
- **troubleshooting.csv** - Common issues and solutions
|
|
225
231
|
|
|
226
232
|
To add new data, edit CSV files directly. No code changes needed.
|
|
@@ -320,14 +326,14 @@ HashIV: 請至後台申請
|
|
|
320
326
|
|
|
321
327
|
Before publishing to npm:
|
|
322
328
|
|
|
323
|
-
1. Update version in `cli/package.json`
|
|
329
|
+
1. Update version in `payment-cli/package.json`
|
|
324
330
|
2. Sync assets: 由 `npm run build` 自動處理(`scripts/sync-assets.mjs`)
|
|
325
|
-
3. Build CLI: `cd cli && npm run build`
|
|
331
|
+
3. Build CLI: `cd payment-cli && npm run build`
|
|
326
332
|
4. Test locally: `npm test`
|
|
327
333
|
5. Publish: `npm publish`
|
|
328
334
|
|
|
329
335
|
## Related Projects
|
|
330
336
|
|
|
331
|
-
- **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego)
|
|
332
|
-
- **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi)
|
|
337
|
+
- **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay)
|
|
338
|
+
- **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow, ezShip, HCT, on-demand delivery)
|
|
333
339
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<h3 align="center">台灣金流 AI 開發技能包</h3>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
6
|
+
<strong>14 家金流平台一次串接</strong>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
<p align="center">
|
|
14
14
|
<a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/v/taiwan-payment-skill?style=flat-square&logo=npm" alt="npm version"></a>
|
|
15
15
|
<a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/dm/taiwan-payment-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
|
|
16
|
-
<img src="https://img.shields.io/badge/providers-
|
|
16
|
+
<img src="https://img.shields.io/badge/providers-14-success?style=flat-square" alt="14 Providers">
|
|
17
17
|
<img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
|
|
18
18
|
<a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
|
|
19
19
|
</p>
|
|
@@ -54,7 +54,7 @@ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動
|
|
|
54
54
|
|
|
55
55
|
---
|
|
56
56
|
|
|
57
|
-
##
|
|
57
|
+
## 14 家金流平台
|
|
58
58
|
|
|
59
59
|
| 服務商 | 加密 / 認證 | 特色 |
|
|
60
60
|
|---|---|---|
|
|
@@ -68,8 +68,12 @@ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動
|
|
|
68
68
|
| **Shopline Payments** | merchantId + apiKey | 金額以分為單位、HMAC-SHA256 webhook |
|
|
69
69
|
| **LINE Pay v4** | Channel ID/Secret + HMAC-SHA256 + Nonce | Request→Confirm 兩段、Preapproved Pay |
|
|
70
70
|
| **TapPay** | Partner Key (Header) | PCI 隔離、Prime 兩段式、Card Token |
|
|
71
|
+
| **O'Pay 歐付寶** | SHA256 CheckMacValue(同 ECPay) | 與 ECPay 同源架構、AccountLink 銀行快付、延遲撥款 |
|
|
72
|
+
| **JKOPAY 街口** | api-key Header + HMAC-SHA256 digest | 線上支付 / POS / 授權扣款 |
|
|
73
|
+
| **SunPay 紅陽** | RSA 分段加密 + SHA256 check_value | 金流 + 發票 + 超商代收 |
|
|
74
|
+
| **GoMyPay** | 需申請文件 | 參數規格待補 |
|
|
71
75
|
|
|
72
|
-
|
|
76
|
+
O'Pay、GoMyPay 以外皆附可執行 Python 範例,加解密以官方測試向量驗證;錯誤碼見 `data/error-codes.csv`。
|
|
73
77
|
|
|
74
78
|
## 技能包內容
|
|
75
79
|
|
|
@@ -77,23 +81,28 @@ TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動
|
|
|
77
81
|
taiwan-payment/
|
|
78
82
|
├── SKILL.md # AI 技能主文檔
|
|
79
83
|
├── EXAMPLES.md # 實戰範例集
|
|
80
|
-
├── references/ #
|
|
84
|
+
├── references/ # 各服務商 API 規格
|
|
81
85
|
│ ├── ecpay-payment-api.md
|
|
82
86
|
│ ├── newebpay-payment-api.md
|
|
83
87
|
│ ├── payuni-payment-api.md
|
|
84
|
-
│ ├── smilepay-payment-api.md #
|
|
88
|
+
│ ├── smilepay-payment-api.md # Mid_smilepay 加權檢核碼
|
|
85
89
|
│ ├── pchomepay-payment-api.md # 含 8h token 流程
|
|
86
90
|
│ ├── ezpay-payment-api.md # 電子支付平台 + 跨境(依官方手冊)
|
|
87
91
|
│ ├── paynow-payment-api.md # 雙 API 並行
|
|
88
92
|
│ ├── shopline-payment-api.md # Redirect + Embedded
|
|
89
93
|
│ ├── linepay-payment-api.md # HMAC + Preapproved
|
|
90
|
-
│
|
|
91
|
-
├──
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
94
|
+
│ ├── tappay-payment-api.md # Prime + Token 重複扣款
|
|
95
|
+
│ ├── opay-payment-api.md
|
|
96
|
+
│ ├── jkopay-payment-api.md
|
|
97
|
+
│ ├── sunpay-payment-api.md
|
|
98
|
+
│ ├── gomypay-payment-api.md
|
|
99
|
+
│ └── twqr-ewallet-landscape.md # 電子支付/TWQR 生態
|
|
100
|
+
├── examples/ # 可執行 Python 範例
|
|
101
|
+
└── data/ # search / recommend 使用的 CSV
|
|
102
|
+
├── providers.csv
|
|
103
|
+
├── operations.csv
|
|
104
|
+
├── payment-methods.csv
|
|
105
|
+
├── error-codes.csv # 各家官方錯誤碼
|
|
97
106
|
└── ...
|
|
98
107
|
```
|
|
99
108
|
|
|
@@ -109,14 +118,14 @@ taiwan-payment init --global # 全域安裝
|
|
|
109
118
|
|
|
110
119
|
## 14 個 AI 平台支援
|
|
111
120
|
|
|
112
|
-
Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder ·
|
|
121
|
+
Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
|
|
113
122
|
|
|
114
123
|
## 相關套件
|
|
115
124
|
|
|
116
125
|
本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
|
|
117
126
|
|
|
118
|
-
- [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) —
|
|
119
|
-
- [taiwan-logistics-skill](https://www.npmjs.com/package/taiwan-logistics-skill) — 7
|
|
127
|
+
- [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 7 家電子發票加值中心 + 財政部大平台查詢
|
|
128
|
+
- [taiwan-logistics-skill](https://www.npmjs.com/package/taiwan-logistics-skill) — 7 家物流 aggregator + HCT 直連 + 3 家即時配送
|
|
120
129
|
|
|
121
130
|
## 授權
|
|
122
131
|
|
|
@@ -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, PayNow, Shopline Payments, LINE Pay v4,
|
|
3
|
+
description: Taiwan Payment API integration specialist for ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay v4, TapPay, O'Pay, JKOPAY, SunPay and GoMyPay. Use when developing payment systems, implementing credit card, ATM, CVS, e-wallet, LINE Pay, Apple Pay, Google Pay, TWQR or BNPL payments, or working with Taiwan payment gateway APIs. Handles encryption (SHA256, AES-256-CBC, AES-256-GCM, dynamic AES-256, RSA, 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 整合開發,包含綠界 (ECPay)、藍新 (NewebPay)、統一 (PAYUNi)、速買配 (SmilePay)、拍錢包 (PChomePay)、ezPay 簡單付、立吉富 (PayNow)、SHOPLINE Payments、LINE Pay v4、TapPay
|
|
9
|
+
> 此技能涵蓋台灣金流 API 整合開發,包含綠界 (ECPay)、藍新 (NewebPay)、統一 (PAYUNi)、速買配 (SmilePay)、拍錢包 (PChomePay)、ezPay 簡單付、立吉富 (PayNow)、SHOPLINE Payments、LINE Pay v4、TapPay、歐付寶 (O'Pay)、街口 (JKOPAY)、紅陽 (SunPay)、GoMyPay 共 14 家服務商。
|
|
10
10
|
|
|
11
11
|
## 快速導覽
|
|
12
12
|
|
|
@@ -22,12 +22,17 @@ user-invocable: true
|
|
|
22
22
|
- `references/shopline-payment-api.md` - Shopline Payments API 規格(Redirect + Embedded SDK 雙模式)
|
|
23
23
|
- `references/linepay-payment-api.md` - LINE Pay v4 API 規格(HMAC-SHA256 + Preapproved Pay)
|
|
24
24
|
- `references/tappay-payment-api.md` - TapPay API 規格(Prime 兩段式 / PCI 隔離 / pay-by-token 重複扣款)
|
|
25
|
+
- `references/opay-payment-api.md` - 歐付寶 O'Pay 全方位金流(與 ECPay 同源的 CheckMacValue 架構)
|
|
26
|
+
- `references/jkopay-payment-api.md` - 街口支付 JKOPAY(線上支付 / POS / 授權扣款,三套簽章並存)
|
|
27
|
+
- `references/sunpay-payment-api.md` - 紅陽 SunPay(RSA 分段加密 + SHA256 check_value)
|
|
28
|
+
- `references/gomypay-payment-api.md` - GoMyPay(完整 API 須洽客服,參數待補)
|
|
29
|
+
- `references/twqr-ewallet-landscape.md` - 電子支付/行動支付生態與 TWQR:全支付、悠遊付等要怎麼收
|
|
25
30
|
- [EXAMPLES.md](EXAMPLES.md) - 程式碼範例集
|
|
26
31
|
|
|
27
32
|
### 智能工具
|
|
28
33
|
- `scripts/search.py` - BM25 搜索引擎(查詢 API、錯誤碼、欄位映射、付款方式)
|
|
29
34
|
- `scripts/recommend.py` - 金流服務商推薦系統
|
|
30
|
-
- `scripts/test_payment.py` -
|
|
35
|
+
- `scripts/test_payment.py` - 已知答案測試 + 測試環境連線
|
|
31
36
|
- `data/` - CSV 數據檔(providers, operations, error-codes, field-mappings, payment-methods, troubleshooting, reasoning)
|
|
32
37
|
|
|
33
38
|
### 何時使用此技能
|
|
@@ -865,9 +870,9 @@ HashIV: 請至後台申請
|
|
|
865
870
|
## 參考資料
|
|
866
871
|
|
|
867
872
|
詳細 API 規格請查看 `references/` 目錄:
|
|
868
|
-
- [綠界 ECPay Payment API 規格](./references/
|
|
869
|
-
- [藍新 NewebPay Payment API 規格](./references/
|
|
870
|
-
- [統一 PAYUNi Payment API 規格](./references/
|
|
873
|
+
- [綠界 ECPay Payment API 規格](./references/ecpay-payment-api.md)
|
|
874
|
+
- [藍新 NewebPay Payment API 規格](./references/newebpay-payment-api.md)
|
|
875
|
+
- [統一 PAYUNi Payment API 規格](./references/payuni-payment-api.md)
|
|
871
876
|
|
|
872
877
|
官方文檔:
|
|
873
878
|
- ECPay: https://developers.ecpay.com.tw/
|
|
@@ -75,6 +75,14 @@ def _canonical(payload: Dict[str, Any]) -> str:
|
|
|
75
75
|
return json.dumps(ordered, separators=(',', ':'), ensure_ascii=False)
|
|
76
76
|
|
|
77
77
|
|
|
78
|
+
def java_urlencode(text: str) -> str:
|
|
79
|
+
"""Java URLEncoder 規則(手冊附錄 3:check_value 必須符合 Java urlencode)。
|
|
80
|
+
|
|
81
|
+
空白編成 `+`、`*` 不編碼、`~` 編成 `%7E`;Python 的 quote 三者都不同。
|
|
82
|
+
"""
|
|
83
|
+
return urllib.parse.quote_plus(text, safe='*').replace('~', '%7E')
|
|
84
|
+
|
|
85
|
+
|
|
78
86
|
def make_check_value(payload: Dict[str, Any], sha2_key: str) -> str:
|
|
79
87
|
"""產生 check_value。
|
|
80
88
|
|
|
@@ -84,7 +92,7 @@ def make_check_value(payload: Dict[str, Any], sha2_key: str) -> str:
|
|
|
84
92
|
`HashKey=...&參數&HashIV=...` 的前後包夾。
|
|
85
93
|
值為 null 的參數不參與簽名(官方明註),本函式已於 build 階段排除。
|
|
86
94
|
"""
|
|
87
|
-
encoded =
|
|
95
|
+
encoded = java_urlencode(_canonical(payload))
|
|
88
96
|
return hashlib.sha256((encoded + sha2_key).encode('utf-8')).hexdigest()
|
|
89
97
|
|
|
90
98
|
|
|
@@ -94,7 +102,7 @@ def make_rsamsg(payload: Dict[str, Any], public_key_pem: str) -> str:
|
|
|
94
102
|
raise RuntimeError('需要 cryptography 套件:pip install cryptography')
|
|
95
103
|
|
|
96
104
|
key = serialization.load_pem_public_key(public_key_pem.encode('utf-8'))
|
|
97
|
-
data =
|
|
105
|
+
data = java_urlencode(_canonical(payload)).encode('utf-8')
|
|
98
106
|
|
|
99
107
|
out = bytearray()
|
|
100
108
|
for i in range(0, len(data), RSA_ENCRYPT_CHUNK):
|
|
@@ -288,7 +296,7 @@ def _self_test() -> int:
|
|
|
288
296
|
failed = 0
|
|
289
297
|
print('紅陽官方測試向量驗證')
|
|
290
298
|
|
|
291
|
-
encoded =
|
|
299
|
+
encoded = java_urlencode(_canonical(payload))
|
|
292
300
|
ok = encoded == expected_encoded
|
|
293
301
|
failed += not ok
|
|
294
302
|
print(f' [{"PASS" if ok else "FAIL"}] urlencode 結果與手冊逐字相同')
|
|
@@ -304,6 +312,12 @@ def _self_test() -> int:
|
|
|
304
312
|
print(f' 期望 {expected_check}')
|
|
305
313
|
print(f' 實得 {got}')
|
|
306
314
|
|
|
315
|
+
# 手冊附錄 3 的 Java URLEncoder 欄:空白 +、~ %7E、* 不編、/ %2F
|
|
316
|
+
got = java_urlencode('a b~c*d/e')
|
|
317
|
+
ok = got == 'a+b%7Ec*d%2Fe'
|
|
318
|
+
failed += not ok
|
|
319
|
+
print(f' [{"PASS" if ok else "FAIL"}] 特殊字元依 Java URLEncoder 編碼(實得 {got})')
|
|
320
|
+
|
|
307
321
|
# send_time 格式:毫秒在最前面、日期在最後
|
|
308
322
|
st = build_send_time(datetime(2023, 9, 27, 16, 21, 34, 585_000))
|
|
309
323
|
ok = st == '585342116' + '20230927'
|
|
@@ -291,7 +291,86 @@ GET https://[Host]/platform/inquiry?platform_order_ids={id1},{id2}
|
|
|
291
291
|
|
|
292
292
|
> 官方範例中第二筆退款紀錄沒有 `refund_order_id`——舊資料可能缺欄,解析時別假設必存在。
|
|
293
293
|
|
|
294
|
-
|
|
294
|
+
### 5.9 店家撥款檔 R File(Reimburse File)
|
|
295
|
+
|
|
296
|
+
線上支付與線下 POS 的 R 檔格式相同(兩份官方頁面欄位逐一一致)。
|
|
297
|
+
|
|
298
|
+
**取得方式**
|
|
299
|
+
|
|
300
|
+
- 街口上傳至街口端 FTP Server;須向業務窗口提供抓檔的來源 IP,審核通過後才給正式/測試 FTP 連線資訊
|
|
301
|
+
- 依請款週期產生,每日 06:00 後可下載
|
|
302
|
+
- 檔名:一般店 `M_ReimburseReport_{店家統編}_{產生日 yyyyMMdd}_R_P.csv`;平台店(僅線上支付頁列出)`…_R_P{Number}.csv`
|
|
303
|
+
- CSV,欄位以 `,` 分隔,每列以 `0d0a`(CRLF)結尾
|
|
304
|
+
- 金額欄一律兩位小數(含小數點),不帶 `+`/`-`;正負由類別欄(`J`/`K`)表示
|
|
305
|
+
|
|
306
|
+
**檔頭 `H`**:資料類別 `H`、檔案日期 `yyyyMMdd`、檔案時間 `HHmm`、預計撥款日期 `yyyyMMdd`
|
|
307
|
+
|
|
308
|
+
**明細 `I`**(依序)
|
|
309
|
+
|
|
310
|
+
| # | 欄位 | 型態(長) | 說明 |
|
|
311
|
+
|---|---|---|---|
|
|
312
|
+
| 1 | 資料類別 | String(1) | `I` |
|
|
313
|
+
| 2 | 交易時間 | String(19) | `TransactionTime`,`yyyy/MM/dd HH:mm:ss` |
|
|
314
|
+
| 3 | 店舖代碼 | String(36) | `StoreID` |
|
|
315
|
+
| 4 | 店舖名稱 | String(70) | 可含中文 |
|
|
316
|
+
| 5 | 交易行為 | String(1) | `1` 支付、`3` 點餐、`5` 外送 |
|
|
317
|
+
| 6 | 交易類別 | String(1) | `J` 付款、`K` 退款 |
|
|
318
|
+
| 7 | 街口端交易序號 | String(50) | `PurchaseNo`(tradeNo) |
|
|
319
|
+
| 8 | 廠商端交易序號 | String(50) | `platform_order_id`;從街口端發起的退款沒有序號,補空白 |
|
|
320
|
+
| 9 | 訂單金額 | Decimal(10) | `BaseAmount` |
|
|
321
|
+
| 10 | 街口配送費 | Decimal(10) | `DeliveryFee`,僅街口配送的外送交易,否則空白 |
|
|
322
|
+
| 11 | 店家街口券折抵 | Decimal(10) | `CouponStoreRedeem`,店家負擔,未使用則空白 |
|
|
323
|
+
| 12 | 官方街口券折抵 | Decimal(10) | `CouponJKORedeem`,街口負擔,未使用則空白 |
|
|
324
|
+
| 13 | 街口幣折抵 | Decimal(10) | `Redeem` |
|
|
325
|
+
| 14 | 支付金額 | Decimal(10) | `PayAmount` = 訂單金額 − 店家/官方券折抵 − 街口幣折抵 + 街口配送費 |
|
|
326
|
+
| 15 | 店家街口幣回饋 | Decimal(8) | 店家負擔,無回饋則空白 |
|
|
327
|
+
| 16 | 支付請款金額 | Decimal(10) | 支付金額 − 支付手續費 − 店家街口幣回饋 − 點餐/外送服務費 − 街口配送費 |
|
|
328
|
+
| 17 | 支付手續費 | Decimal(8) | (支付金額 − 街口配送費)× 支付費率 |
|
|
329
|
+
| 18 | 點餐/外送服務費 | Decimal(8) | 訂單金額 × 點餐/外送費率,非此類交易空白 |
|
|
330
|
+
| 19 | 街口幣折抵請款金額 | Decimal(10) | 街口幣折抵 − 街口幣折抵手續費 |
|
|
331
|
+
| 20 | 街口幣折抵手續費 | Decimal(8) | 街口幣折抵 × 折抵費率 |
|
|
332
|
+
| 21 | 官方街口券折抵請款金額 | Decimal(10) | 官方券折抵 − 官方券折抵手續費 |
|
|
333
|
+
| 22 | 官方街口券折抵手續費 | Decimal(8) | 官方券折抵 × 折抵費率 |
|
|
334
|
+
| 23–25 | 保留欄位 ×3 | String(30) | 補空白 |
|
|
335
|
+
|
|
336
|
+
**檔尾 `T`**(依序)
|
|
337
|
+
|
|
338
|
+
| # | 欄位 | 型態(長) | 說明 |
|
|
339
|
+
|---|---|---|---|
|
|
340
|
+
| 1 | 資料類別 | String(1) | `T` |
|
|
341
|
+
| 2 | 總筆數 | Decimal(8) | 明細筆數 |
|
|
342
|
+
| 3 | 訂單總金額 | Decimal(12) | |
|
|
343
|
+
| 4 | 支付總金額 | Decimal(12) | |
|
|
344
|
+
| 5 | 支付總手續費 | Decimal(8) | 支付手續費 + 店家回饋街口幣 + 點餐/外送服務費 |
|
|
345
|
+
| 6 | 支付總請款金額 | Decimal(12) | |
|
|
346
|
+
| 7 | 街口幣折抵總金額 | Decimal(12) | 紅利月結店家一律 `0.00` |
|
|
347
|
+
| 8 | 街口幣折抵總手續費 | Decimal(8) | 紅利月結店家一律 `0.00` |
|
|
348
|
+
| 9 | 街口幣折抵總請款金額 | Decimal(12) | |
|
|
349
|
+
| 10 | 官方街口券折抵總金額 | Decimal(12) | 紅利月結店家一律 `0.00` |
|
|
350
|
+
| 11 | 官方街口券折抵總手續費 | Decimal(8) | 紅利月結店家一律 `0.00` |
|
|
351
|
+
| 12 | 官方街口券折抵總請款金額 | Decimal(12) | |
|
|
352
|
+
| 13 | 店家街口券折抵總金額型別 | String(1) | `J` 退還店家、`K` 向店家收取 |
|
|
353
|
+
| 14 | 店家街口券折抵總金額 | Decimal(12) | 全數店家負擔 |
|
|
354
|
+
| 15 | 街口券發送費 | Decimal(12) | `SendingFee` 加總 |
|
|
355
|
+
| 16 | 街口券折抵費型別 | String(1) | `J` 退還店家、`K` 向店家收取 |
|
|
356
|
+
| 17 | 街口券折抵費 | Decimal(12) | `UsageFee` 加總 |
|
|
357
|
+
| 18 | 調帳金額型別 | String(1) | `J` 調帳補匯、`K` 調帳扣回 |
|
|
358
|
+
| 19 | 調帳金額 | Decimal(8) | |
|
|
359
|
+
| 20 | 匯費 | Decimal(8) | 銀行匯款手續費 |
|
|
360
|
+
| 21 | 總撥款金額 | Decimal(12) | 支付總請款 + 街口幣總請款 + 官方券總請款 + 調帳 − 街口券發送費 − 街口券折抵費 − 匯費,已四捨五入到整數 |
|
|
361
|
+
| 22–24 | 保留欄位 ×3 | String(30) | 補空白 |
|
|
362
|
+
|
|
363
|
+
官方範例:
|
|
364
|
+
|
|
365
|
+
```
|
|
366
|
+
H,20190708,0500,2019070900
|
|
367
|
+
I,2019/07/07 12:00:00,d7120db2-8c76-4124-bf08-02e5b775d8fe,哈拉股份有限公司,1,J,J0026910118070413C4,19070710026C8N8,1000.00,,200.00,, 200.00,600.00,,586.80,13.20,,195.60,4.40,,,,,,
|
|
368
|
+
I,2019/07/07 12:30:00, d7120db2-8c76-4124-bf08-02e5b775d8fe,哈拉股份有限公司,1,J,J0026910118070413C5,190707214361GPU,1000.00,,,200.00, 200.00,600.00,,586.80,13.20,,195.60,4.40,195.60,4.40,,,,
|
|
369
|
+
I,2019/07/07 12:55:20,d7120db2-8c76-4124-bf08-02e5b775d8fe,哈拉股份有限公司,1, K,K0026910118070413C4001,,1000.00,,,,200.00,800.00,,782.40,17.60,,195.60,4.40,,,,,,
|
|
370
|
+
T,3,2000.00,400.00,8.80,391.20,200.00,4.40,195.60,200.00,4.40,195.60, K,200.00,1.00,K,2.00,J,0.00,5.00,774.40,,,,
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
> ⚠️ 官方範例與欄位表有出入,解析時要寬鬆:檔頭預計撥款日期寫成 10 碼(`2019070900`,表定 8 碼);部分欄位前帶空白(`, 200.00`、`, K`),先 `trim` 再判斷。
|
|
295
374
|
|
|
296
375
|
## 6. 授權扣款 Authorized Payment — 完整規格
|
|
297
376
|
|
|
@@ -445,7 +524,7 @@ Response 的 `result_object` 與 OnlinePay 的 `result_url` 同構(`tradeNo`
|
|
|
445
524
|
|
|
446
525
|
`POST https://pos.jkopay.com/{系統方名稱}/Payment`
|
|
447
526
|
|
|
448
|
-
端點:付款 / 取消 / 退款 / 查詢 / 店家撥款檔(R
|
|
527
|
+
端點:付款 / 取消 / 退款 / 查詢 / 店家撥款檔(R 檔,格式見 §5.9)。
|
|
449
528
|
|
|
450
529
|
### 簽章(與線上支付完全不同)
|
|
451
530
|
|
|
@@ -543,7 +622,7 @@ Response 另含 `RefundTradeNo`、`RefundTradeTime`、`IsRep`、`PaymentType`、
|
|
|
543
622
|
|
|
544
623
|
> 對帳程式若用同一個函式處理折抵金額,跨模組時金額會反號。建議在解析層就依來源正規化,不要在計算層才處理。
|
|
545
624
|
|
|
546
|
-
## 9. inApp 第三方服務 — OAuth / JOP Gateway
|
|
625
|
+
## 9. inApp 第三方服務 — OAuth / JOP Gateway / Web SDK
|
|
547
626
|
|
|
548
627
|
給 ISV 業者取得街口使用者授權資料用,**網域與支付 API 完全不同**:
|
|
549
628
|
|
|
@@ -592,6 +671,30 @@ Response 另含 `RefundTradeNo`、`RefundTradeTime`、`IsRep`、`PaymentType`、
|
|
|
592
671
|
|
|
593
672
|
OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-360` Auth Code 過期、`OA-999` 系統異常;`UP-001` 成功、`UP-360` Auth Code 過期、`UP-460` **Access Token 過期**、`UP-999`;通用 `205` 參數錯誤、`405` 權限不足、`999` 網關異常。
|
|
594
673
|
|
|
674
|
+
### Web SDK(`@jkos/openweb-bridge`)
|
|
675
|
+
|
|
676
|
+
在街口 App 的 webview 內呼叫原生能力(授權、導航欄、路由、介面交互),全域物件為 `jkos`。
|
|
677
|
+
|
|
678
|
+
**版本與載入**(官方「SDK 版本」頁)
|
|
679
|
+
|
|
680
|
+
| 版本 | UMD | CJS | 變動 | 上版日 |
|
|
681
|
+
|---|---|---|---|---|
|
|
682
|
+
| 2.0.7 | `https://upkg.jkos.com/openweb-bridge/v2.0.7/jkos.umd.js` | `@jkos/openweb-bridge@2.0.7-prod` | 新增 `close` | 2022/08/10 |
|
|
683
|
+
| 2.0.6 | `…/v2.0.6/jkos.umd.js` | `@jkos/openweb-bridge@2.0.6-prod` | 新增 `setNavRightButton`、`setPullRefreshOn` | 2022/02/14 |
|
|
684
|
+
| 2.0.4 | `…/v2.0.4/jkos.umd.js` | `@jkos/openweb-bridge@2.0.4-prod` | 新增 `showModal` | 2021/11/16 |
|
|
685
|
+
| 2.0.3 | `…/v2.0.3/jkos.umd.js` | `@jkos/openweb-bridge@2.0.3-prod` | 新增 `openBrowser`、`redirectMaintainPage` | 2021/09/30 |
|
|
686
|
+
| 2.0.2 | `…/v2.0.2/jkos.umd.js` | `@jkos/openweb-bridge@2.0.2-prod` | `setNavRightButton` 我的按鈕 onClick | 2021/09/14 |
|
|
687
|
+
| 2.0.1 | `…/v2.0.1/jkos.umd.js` | `@jkos/openweb-bridge@2.0.1-prod` | 修正取得環境資訊 | 2021/09/05 |
|
|
688
|
+
|
|
689
|
+
- npm 套件在街口自有 registry:`https://npmjs.jkos.com/-/web/detail/@jkos/openweb-bridge`
|
|
690
|
+
- ⚠️ **v2.0.6 與先前版本不相容**:使用 v2.0.4(含)以下者,升級前須先聯絡街口窗口
|
|
691
|
+
- 文件另有 v2.0.8 與 Next 兩組 API 頁面,但版本表未列其 UMD/套件位址;官方未標示建議版本,採用前向街口窗口確認
|
|
692
|
+
|
|
693
|
+
**Next 版 API**:`getAuthCode`(喚起原生授權頁取得 auth code,接 §9 OAuth)、`setNavTitle`、`setNavBackground`、`setNavLeftButton`、`setNavRightButton`、`clearNavRightButton`、`openBrowser`、`redirectMaintainPage`、`close`、`showModal`、`setPullRefreshOn`/`setPullRefreshOff`。
|
|
694
|
+
呼叫形式 `jkos.xxx(data, callback)`,callback 收 `{ error, errorMessage }`,也可改用 async/await。
|
|
695
|
+
|
|
696
|
+
**SDK 錯誤碼**:`0` 成功、`15` App 版本不支援該函式版本、`16` 格式錯誤、`17` 須在支援的街口 webview 入口開啟、`18` 無法取得 App 環境資訊、`19` App 版本找不到該函式、`206` 無效的 ClientID、`207` 無效的 Scope。
|
|
697
|
+
|
|
595
698
|
## 10. 統一錯誤代碼表(線下 POS)
|
|
596
699
|
|
|
597
700
|
`StatusCode`,共 33 個代碼。**這是街口唯一一份「統一」錯誤碼表**,掛在 POS 模組下。
|
|
@@ -708,13 +811,11 @@ OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-
|
|
|
708
811
|
|
|
709
812
|
## 12. 仍待補
|
|
710
813
|
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
|
714
|
-
|
|
715
|
-
| R
|
|
716
|
-
| Web SDK | 低 | 版本多(v2.0.2–v2.0.8 + Next),需先確認採用版本 |
|
|
717
|
-
| 街口幣查詢 API | — | **官方尚未提供**,僅先公布簽章格式 |
|
|
814
|
+
| 待補項目 | 備註 |
|
|
815
|
+
|---|---|
|
|
816
|
+
| 街口幣查詢 API | **官方尚未提供**,僅先公布簽章格式 |
|
|
817
|
+
| Web SDK v2.0.8/Next 的載入位址與建議版本 | 官方版本表只列到 2.0.7,需向街口窗口確認 |
|
|
818
|
+
| R 檔 FTP 連線資訊 | 須提供來源 IP 給業務窗口審核後才提供 |
|
|
718
819
|
|
|
719
820
|
## 13. 來源
|
|
720
821
|
|
|
@@ -724,6 +825,10 @@ OAuth 專屬錯誤碼:`OA-001` 成功、`OA-205` Auth Code 已被使用、`OA-
|
|
|
724
825
|
- 加簽加密說明 — `…/線上支付onlinepay/串接說明/加簽加密說明`
|
|
725
826
|
- 訂單創建 Entry API — `…/線上支付onlinepay/api列表/訂單創建-api`
|
|
726
827
|
- 代碼意義 API Response Code — `…/線上支付onlinepay/api列表/代碼意義`
|
|
828
|
+
- 店家撥款檔 R 檔(線上支付)— `…/線上支付onlinepay/api列表/店家撥款檔r檔`
|
|
829
|
+
- 店家撥款檔 R 檔(線下 POS)— `…/線下交易pos/api列表/店家撥款檔r檔`
|
|
830
|
+
- Web SDK 版本 — https://open-doc.jkos.com/?docs=inapp-第三方服務/web-sdk/sdk-環境版本
|
|
831
|
+
- Web SDK Next — `…/inapp-第三方服務/web-sdk/next`(基礎開放能力、介面交互、按鈕、錯誤代碼)
|
|
727
832
|
- 授權扣款 Authorized Payment — https://open-doc.jkos.com/?docs=授權扣款-authorized-payment
|
|
728
833
|
- 授權創建 Binding — `…/授權扣款-authorized-payment/api列表-api-lists/授權綁定創建-authorization-binding`
|
|
729
834
|
- 授權綁定結果通知 CallBack — `…/api列表-api-lists/授權綁定結果通知-authorization-callback`
|
|
@@ -101,7 +101,7 @@ Form POST,`application/x-www-form-urlencoded`。
|
|
|
101
101
|
| `IgnorePayment` | String(100) | `ChoosePayment=ALL` 時隱藏特定付款方式,多筆以 `#` 分隔 |
|
|
102
102
|
| `DeviceSource` | String(10) | 空值=預設版型;`APP`=App 版型 |
|
|
103
103
|
| `PlatformID` | String(10) | 平台商代號。**有帶此參數時,檢查碼須用平台商的 HashKey/HashIV 計算** |
|
|
104
|
-
| `HoldTradeAMT` | Int | `0`=不延遲撥款(預設);`1`=延遲撥款,需另呼叫「會員申請撥款/退款」API
|
|
104
|
+
| `HoldTradeAMT` | Int | `0`=不延遲撥款(預設);`1`=延遲撥款,需另呼叫「會員申請撥款/退款」API(`Cashier/Capture`,見第 5 節)。**不適用信用卡** |
|
|
105
105
|
| `UseRedeem` | String(1) | `Y`/`N`,是否可用購物金/紅包折抵 |
|
|
106
106
|
| `Remark` / `ItemURL` | String | 備註 / 商品銷售網址 |
|
|
107
107
|
| `ChooseSubPayment` | String(20) | 付款子項目(如 `TAISHIN`) |
|
|
@@ -226,6 +226,31 @@ def gen_check_mac_value(params: dict, hash_key: str, hash_iv: str) -> str:
|
|
|
226
226
|
- 已關帳的信用卡訂單**不適用**,請用「信用卡關帳/退刷/取消/放棄」
|
|
227
227
|
- 微信支付已撥款者無法用 API 退款,僅能人工處理(洽客服 02-2655-0115)
|
|
228
228
|
|
|
229
|
+
### 會員申請撥款/退款 `Cashier/Capture`
|
|
230
|
+
|
|
231
|
+
延遲撥款(`HoldTradeAMT=1`)的交易付款後,呼叫此 API 讓歐付寶撥款到會員帳戶,並可同時退款給買方(《全方位金流介接技術文件》第 13 章,p.41–42)。
|
|
232
|
+
非延遲撥款的交易改用 `AioChargeback`;**信用卡交易不適用**。
|
|
233
|
+
|
|
234
|
+
- 正式:`https://payment.opay.tw/Cashier/Capture`
|
|
235
|
+
- 測試:`https://payment-stage.opay.tw/Cashier/Capture`
|
|
236
|
+
- Server POST,CheckMacValue 同第 4 節
|
|
237
|
+
|
|
238
|
+
| 參數 | 型態 | 必填 | 說明 |
|
|
239
|
+
|------|------|:---:|------|
|
|
240
|
+
| `MerchantID` | String(10) | ● | 會員編號 |
|
|
241
|
+
| `MerchantTradeNo` | String(64) | ● | 建立訂單時的會員交易編號 |
|
|
242
|
+
| `CheckMacValue` | String | ● | |
|
|
243
|
+
| `CaptureAMT` | Int | ● | 申請撥款金額 |
|
|
244
|
+
| `UserRefundAMT` | Int | ● | 退款給買方的金額,不退款帶 `0`;範圍 0~訂單金額。**`CaptureAMT + UserRefundAMT` 須等於訂單金額** |
|
|
245
|
+
| `PlatformID` | String(10) | | 專案合作平台商代號;一般會員帶空值 |
|
|
246
|
+
| `UpdatePlatformChargeFee` | String(1) | | `Y` 更改訂單的平台商手續費,預設 `N`;僅平台商使用 |
|
|
247
|
+
| `PlatformChargeFee` | Int | | `UpdatePlatformChargeFee=Y` 時帶,範圍 0~原手續費 |
|
|
248
|
+
| `Remark` | String(30) | | 備註 |
|
|
249
|
+
|
|
250
|
+
實際撥款金額 = 訂單金額 − `UserRefundAMT` − 必要手續費。
|
|
251
|
+
|
|
252
|
+
回應以 `參數=值&…` 直接回傳:`MerchantID`、`MerchantTradeNo`、`TradeNo`(String(20))、`RtnCode`(`1` 成功,其餘失敗)、`RtnMsg`、`AllocationDate`(預計撥款日 `yyyy-MM-dd`)。
|
|
253
|
+
|
|
229
254
|
### 其他端點
|
|
230
255
|
|
|
231
256
|
| 功能 | 路徑 |
|
|
@@ -266,8 +291,7 @@ def gen_check_mac_value(params: dict, hash_key: str, hash_iv: str) -> str:
|
|
|
266
291
|
| 會員 Open ID API | https://www.opay.tw/Content/files/O_Pay_041.pdf |
|
|
267
292
|
| 電子發票 B2C / B2B / 離線 | 見 [../../taiwan-invoice/references/OPAY_API_REFERENCE.md](../../taiwan-invoice/references/OPAY_API_REFERENCE.md) |
|
|
268
293
|
|
|
269
|
-
## 8.
|
|
294
|
+
## 8. 備註與待驗證
|
|
270
295
|
|
|
271
296
|
- POS、微信公眾號文件標註「若要串接使用請洽歐付寶客服」,可能需額外開通
|
|
272
|
-
-
|
|
273
|
-
- 「會員申請撥款/退款」API(延遲撥款情境)的完整參數本次未擷取
|
|
297
|
+
- 歐付寶沒有公開物流 API:官方文件總覽(2026-09-21 修訂版,2026-09-24 查核)只列金流、電子發票、Open ID、平台綁定、直播主收款網址
|