taiwan-payment-skill 1.5.14 → 1.5.15

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.
Files changed (75) hide show
  1. package/README.md +138 -139
  2. package/assets/taiwan-payment/CLAUDE.md +339 -339
  3. package/assets/taiwan-payment/EXAMPLES.md +1402 -1392
  4. package/assets/taiwan-payment/README.md +138 -139
  5. package/assets/taiwan-payment/README.zh-TW.md +138 -0
  6. package/assets/taiwan-payment/SKILL.md +152 -151
  7. package/assets/taiwan-payment/data/error-codes-payuni-1.csv +786 -786
  8. package/assets/taiwan-payment/data/error-codes-payuni-2.csv +719 -719
  9. package/assets/taiwan-payment/data/error-codes-tappay.csv +474 -474
  10. package/assets/taiwan-payment/data/error-codes.csv +1047 -1004
  11. package/assets/taiwan-payment/data/field-mappings.csv +20 -20
  12. package/assets/taiwan-payment/data/operations.csv +26 -26
  13. package/assets/taiwan-payment/data/payment-methods.csv +42 -42
  14. package/assets/taiwan-payment/data/pending.csv +59 -8
  15. package/assets/taiwan-payment/data/providers.csv +15 -15
  16. package/assets/taiwan-payment/data/reasoning.csv +46 -46
  17. package/assets/taiwan-payment/data/troubleshooting.csv +47 -47
  18. package/assets/taiwan-payment/evals/RESULTS.md +33 -33
  19. package/assets/taiwan-payment/evals/cases.json +192 -192
  20. package/assets/taiwan-payment/evals/grade.py +121 -121
  21. package/assets/taiwan-payment/examples/ecpay-payment-example.py +415 -415
  22. package/assets/taiwan-payment/examples/ezpay-payment-example.py +366 -366
  23. package/assets/taiwan-payment/examples/jkopay-payment-example.py +316 -316
  24. package/assets/taiwan-payment/examples/linepay-payment-example.py +305 -310
  25. package/assets/taiwan-payment/examples/newebpay-payment-example.py +609 -607
  26. package/assets/taiwan-payment/examples/paynow-payment-example.py +759 -767
  27. package/assets/taiwan-payment/examples/payuni-payment-example.py +301 -301
  28. package/assets/taiwan-payment/examples/pchomepay-payment-example.py +558 -555
  29. package/assets/taiwan-payment/examples/shopline-payment-example.py +286 -290
  30. package/assets/taiwan-payment/examples/smilepay-payment-example.py +673 -673
  31. package/assets/taiwan-payment/examples/sunpay-payment-example.py +343 -343
  32. package/assets/taiwan-payment/examples/tappay-payment-example.py +339 -336
  33. package/assets/taiwan-payment/references/audit-20261117.md +432 -0
  34. package/assets/taiwan-payment/references/ecpay-payment-api.md +552 -502
  35. package/assets/taiwan-payment/references/ezpay-payment-api.md +475 -460
  36. package/assets/taiwan-payment/references/gomypay-payment-api.md +58 -50
  37. package/assets/taiwan-payment/references/implementation-guide.md +771 -768
  38. package/assets/taiwan-payment/references/jkopay-payment-api.md +841 -840
  39. package/assets/taiwan-payment/references/linepay-payment-api.md +1017 -930
  40. package/assets/taiwan-payment/references/newebpay-payment-api.md +855 -829
  41. package/assets/taiwan-payment/references/opay-payment-api.md +580 -565
  42. package/assets/taiwan-payment/references/paynow-payment-api.md +1752 -1651
  43. package/assets/taiwan-payment/references/payuni-payment-api.md +883 -847
  44. package/assets/taiwan-payment/references/pchomepay-payment-api.md +1431 -1428
  45. package/assets/taiwan-payment/references/shopline-payment-api.md +1559 -1524
  46. package/assets/taiwan-payment/references/smilepay-payment-api.md +913 -907
  47. package/assets/taiwan-payment/references/sunpay-payment-api.md +479 -467
  48. package/assets/taiwan-payment/references/tappay-payment-api.md +1375 -1243
  49. package/assets/taiwan-payment/references/twqr-ewallet-landscape.md +159 -159
  50. package/assets/taiwan-payment/requirements.txt +4 -4
  51. package/assets/taiwan-payment/scripts/check_numbers.py +205 -147
  52. package/assets/taiwan-payment/scripts/core.py +368 -368
  53. package/assets/taiwan-payment/scripts/recommend.py +288 -288
  54. package/assets/taiwan-payment/scripts/search.py +200 -200
  55. package/assets/taiwan-payment/scripts/test_payment.py +395 -395
  56. package/assets/taiwan-payment/scripts/test_recommend.py +114 -114
  57. package/assets/taiwan-payment/scripts/test_skill.py +202 -202
  58. package/assets/templates/base/quick-reference.md +70 -70
  59. package/assets/templates/base/skill-content.md +148 -147
  60. package/assets/templates/platforms/agent.json +26 -26
  61. package/assets/templates/platforms/claude.json +26 -26
  62. package/assets/templates/platforms/cline.json +26 -26
  63. package/assets/templates/platforms/codebuddy.json +25 -25
  64. package/assets/templates/platforms/codex.json +26 -26
  65. package/assets/templates/platforms/continue.json +25 -25
  66. package/assets/templates/platforms/copilot.json +25 -25
  67. package/assets/templates/platforms/cursor.json +26 -26
  68. package/assets/templates/platforms/gemini.json +25 -25
  69. package/assets/templates/platforms/kiro.json +25 -25
  70. package/assets/templates/platforms/opencode.json +25 -25
  71. package/assets/templates/platforms/qoder.json +25 -25
  72. package/assets/templates/platforms/trae.json +25 -25
  73. package/assets/templates/platforms/windsurf.json +25 -25
  74. package/dist/index.js +1 -1
  75. package/package.json +67 -67
package/README.md CHANGED
@@ -1,139 +1,138 @@
1
- <h1 align="center">taiwan-payment-skill</h1>
2
-
3
- <h3 align="center">台灣金流 AI 開發技能包</h3>
4
-
5
- <p align="center">
6
- <strong>14 家金流平台一次串接</strong>
7
- </p>
8
-
9
- <p align="center">
10
- ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · ezPay · PayNow · Shopline · LINE Pay · TapPay
11
- </p>
12
-
13
- <p align="center">
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
- <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-14-success?style=flat-square" alt="14 Providers">
17
- <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
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
- </p>
20
-
21
- <p align="center">
22
- <a href="https://paypal.me/cccsubcom"><img src="https://img.shields.io/badge/PayPal-支持開發-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal"></a>
23
- </p>
24
-
25
- ---
26
-
27
- ## 安裝
28
-
29
- ```bash
30
- npm install -g taiwan-payment-skill
31
- ```
32
-
33
- ## 快速開始
34
-
35
- ```bash
36
- cd /path/to/your/project
37
-
38
- taiwan-payment init # 互動式
39
- taiwan-payment init --ai claude # Claude Code
40
- taiwan-payment init --ai cursor # Cursor
41
- taiwan-payment init --ai windsurf # Windsurf
42
- taiwan-payment init --ai all # 全部安裝
43
- ```
44
-
45
- 安裝完後,AI 助手裡用自然語言:
46
-
47
- ```
48
- 建立 ECPay 信用卡付款訂單,金額 2500 元
49
- NewebPay MPG 整合 LINE Pay + Apple Pay
50
- PChomePay 拍錢包訂單,5% P 幣回饋
51
- PayNow PaymentIntent,啟用 LINE Pay 線上+線下扣款
52
- TapPay 用 Prime 一次付清,remember=true 存成 card_token 供下次自動扣款
53
- ```
54
-
55
- ---
56
-
57
- ## 14 家金流平台
58
-
59
- | 服務商 | 加密 / 認證 | 特色 |
60
- |---|---|---|
61
- | **ECPay 綠界** | SHA256 CheckMacValue | 市佔率最高、文檔最完整 |
62
- | **NewebPay 藍新** | AES-256-CBC + SHA256 | MPG 整合、信用卡記憶、13 種支付 |
63
- | **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON、AFTEE、iCash |
64
- | **SmilePay 速買配** | Verify_key + 加權檢核碼 | 無 AES、ibon / FamiPort 直接打單 |
65
- | **PChomePay 拍錢包** | Basic Auth → 8h pcpay-token | PChome 生態、5% P 幣回饋、金物流二合一 |
66
- | **ezPay 簡單付** | AES-256-CBC(32-byte padding)+ SHA256 | 電子支付機構;境內 TWQR / ezPay 錢包,跨境支付寶 / 微信 |
67
- | **PayNow 立吉富** | JWT Bearer (現代) / 動態 AES-256 (傳統) | 雙 API、Stripe-like、Apple Pay 完整 |
68
- | **Shopline Payments** | merchantId + apiKey | 金額以分為單位、HMAC-SHA256 webhook |
69
- | **LINE Pay v4** | Channel ID/Secret + HMAC-SHA256 + Nonce | Request→Confirm 兩段、Preapproved Pay |
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** | 需向 GoMyPay 申請規格 | 完整 API 規格未公開 |
75
-
76
- O'Pay、GoMyPay 以外皆附可執行 Python 範例,加解密以官方測試向量驗證;錯誤碼見 `data/error-codes*.csv`。
77
-
78
- ## 技能包內容
79
-
80
- ```
81
- taiwan-payment/
82
- ├── SKILL.md # AI 技能主文檔
83
- ├── EXAMPLES.md # 實戰範例集
84
- ├── references/ # 各服務商 API 規格
85
- │ ├── ecpay-payment-api.md
86
- │ ├── newebpay-payment-api.md
87
- │ ├── payuni-payment-api.md
88
- │ ├── smilepay-payment-api.md # Mid_smilepay 加權檢核碼
89
- │ ├── pchomepay-payment-api.md # 含 8h token 流程
90
- │ ├── ezpay-payment-api.md # 電子支付平台 + 跨境(依官方手冊)
91
- │ ├── paynow-payment-api.md # 雙 API 並行
92
- │ ├── shopline-payment-api.md # Redirect + Embedded
93
- │ ├── linepay-payment-api.md # HMAC + Preapproved
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 # 各家官方錯誤碼(依 256 KiB 上限分檔)
106
- └── ...
107
- ```
108
-
109
- ## CLI 指令
110
-
111
- ```bash
112
- taiwan-payment list # 列出 AI 平台
113
- taiwan-payment info # 技能資訊
114
- taiwan-payment update # 檢查更新
115
- taiwan-payment init --force # 覆蓋安裝
116
- taiwan-payment init --global # 全域安裝
117
- ```
118
-
119
- ## 14 個 AI 平台支援
120
-
121
- Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
122
-
123
- ## 相關套件
124
-
125
- 本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
126
-
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 直連 + 2 家即時配送
129
-
130
- ## 授權
131
-
132
- [MIT License](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE)
133
-
134
- ---
135
-
136
- <p align="center">
137
- <sub>Made by <strong>Moksa</strong></sub><br>
138
- <sub>service@moksaweb.com</sub>
139
- </p>
1
+ # taiwan-payment
2
+
3
+ A Claude skill for integrating Taiwan payment gateways: request signing, encryption, payment callbacks, refunds and error codes, based on each provider's official documentation.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/taiwan-payment-skill)](https://www.npmjs.com/package/taiwan-payment-skill)
6
+ [![License: MIT](https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit)](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE)
7
+
8
+ English | [繁體中文](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-payment/README.zh-TW.md)
9
+
10
+ This is an unofficial project. It is not affiliated with or endorsed by ECPay, NewebPay, PAYUNi, LINE, TapPay, JKOPAY or any other company named here. Brand names are written the way each company writes them and belong to their owners.
11
+
12
+ ## What it does
13
+
14
+ - Covers 14 Taiwan payment providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline Payments, LINE Pay v4, TapPay, O'Pay, JKOPAY, SunPay and GoMyPay.
15
+ - Gives Claude each provider's signing and encryption rules (CheckMacValue, TradeSha, AES-256-CBC, AES-256-GCM, RSA, JWT, HMAC-SHA256) with runnable Python examples.
16
+ - Searches 3212 rows of official data offline with `scripts/search.py`: error codes, API operations, field mappings, payment methods and troubleshooting notes.
17
+ - Suggests a provider from plain-language requirements with `scripts/recommend.py`.
18
+ - Links each task (credit card, ATM, CVS code, e-wallet, Apple Pay, Google Pay, TWQR, BNPL, recurring billing, refunds) to the right reference file in `references/`.
19
+
20
+ ## When to use
21
+
22
+ Use it when you are:
23
+
24
+ - building or debugging a checkout that talks to one of the providers above;
25
+ - verifying a payment notification (CheckMacValue, TradeSha, HashInfo, webhook signatures);
26
+ - looking up what a provider's error or status code means;
27
+ - choosing between providers for a project.
28
+
29
+ Use something else for:
30
+
31
+ - issuing, voiding or adjusting e-invoices: use [taiwan-invoice](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/tree/main/taiwan-invoice);
32
+ - shipping, convenience-store pickup, store maps or tracking, even with ECPay, NewebPay or PAYUNi: use [taiwan-logistics](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/tree/main/taiwan-logistics);
33
+ - payment providers outside Taiwan, or direct bank and card-network integrations: not covered.
34
+
35
+ ## Install
36
+
37
+ Requirements: Python 3 for the scripts, which use only the standard library. The files in `examples/` and the network options of `scripts/test_payment.py` also need `pycryptodome` (AES) and `requests`; install them with `pip install -r requirements.txt`. Node.js 18 or later is needed only for the npx installer. Works on Windows, macOS and Linux.
38
+
39
+ Claude Code plugin (installs all three Taiwan skills: invoice, payment, logistics):
40
+
41
+ ```text
42
+ /plugin marketplace add Moksa1123/taiwan-ecommerce-toolkit
43
+ /plugin install taiwan-ecommerce@taiwan-ecommerce-toolkit
44
+ ```
45
+
46
+ npx (copies the skill into the current project; `--ai` also accepts other agents such as `cursor` or `codex`, `--global` installs into your home directory):
47
+
48
+ ```bash
49
+ npx taiwan-payment-skill@1.5.15 init --ai claude
50
+ ```
51
+
52
+ Manual copy:
53
+
54
+ ```bash
55
+ git clone https://github.com/Moksa1123/taiwan-ecommerce-toolkit.git
56
+ cp -r taiwan-ecommerce-toolkit/taiwan-payment ~/.claude/skills/
57
+ ```
58
+
59
+ ## Quick start
60
+
61
+ Ask Claude, for example:
62
+
63
+ - "Create an ECPay credit-card order in Python and verify the payment notification."
64
+ - "My NewebPay TradeInfo fails to decrypt. What is wrong with my padding?"
65
+ - "Which provider should I use for LINE Pay plus recurring card payments?"
66
+
67
+ Or search the data yourself from the skill folder:
68
+
69
+ ```bash
70
+ python3 scripts/search.py "10100058" --domain error --max 1
71
+ ```
72
+
73
+ Expected output (shortened):
74
+
75
+ ```text
76
+ 搜索域: error
77
+ 找到 1 筆結果
78
+ [結果 #1] 評分: 6.04
79
+ Provider : ecpay
80
+ Code : 10100058
81
+ Message Zh : Pay fail(3D 驗證未完成)
82
+ Solution : 請消費者更換瀏覽器或裝置、關閉 VPN、切換網路取得新 IP;...
83
+ Doc Url : https://developers.ecpay.com.tw/
84
+ Trust : 官方文件
85
+ ```
86
+
87
+ ## Trigger phrases
88
+
89
+ English: Taiwan payment gateway, ECPay, NewebPay, PAYUNi, LINE Pay, TapPay, JKOPAY, credit card payment, ATM virtual account, CVS payment code, Apple Pay, Google Pay, TWQR, BNPL, CheckMacValue, payment notification, refund, recurring payment.
90
+
91
+ 中文:金流串接、綠界、藍新、統一金流、信用卡付款、ATM 虛擬帳號、超商代碼、LINE Pay、Apple Pay、街口、CheckMacValue、TradeSha、付款通知、退款、定期定額。
92
+
93
+ ## What it runs and connects to
94
+
95
+ The skill is Markdown documentation, CSV data and local Python scripts. It never sends data anywhere on its own. Network calls happen only when you run a connectivity option of the test script or run an example file.
96
+
97
+ | Script | What it does | Network | Files written |
98
+ |---|---|---|---|
99
+ | `scripts/search.py` | Searches `data/*.csv` | None | None |
100
+ | `scripts/recommend.py` | Suggests a provider from `data/*.csv` | None | None |
101
+ | `scripts/test_payment.py` | Known-answer tests of ECPay, NewebPay and PAYUNi signing; offline by default | `--live`: HEAD request to the sandbox of ECPay (`payment-stage.ecpay.com.tw`), NewebPay (`ccore.newebpay.com`) and PAYUNi (`sandbox-api.payuni.com.tw`). `--query`: POST to the ECPay sandbox order query | `--create`: an `ecpay_test_<order>.html` form in the current folder |
102
+ | `scripts/check_numbers.py` | Checks that every number in `SKILL.md` and these READMEs matches the data | None | With `--fix`, those three files |
103
+ | `scripts/test_skill.py` | Self-test; runs the checks above offline | None | None |
104
+ | `examples/*.py` | Reference clients for each provider | When run directly, calls the sandbox or production host defined at the top of that file | None |
105
+
106
+ Credentials (merchant ID, HashKey and HashIV, LINE Pay Channel ID and Channel Secret, TapPay Partner Key, API keys) are supplied by you in your own code or configuration, for example environment variables. The repository stores no real credentials. Test values that appear in the docs and scripts are the providers' published sandbox values.
107
+
108
+ ## How it's verified
109
+
110
+ - Data source: official provider documentation, PDF specifications and official SDKs or plugins. Every source is registered in [`sources/official-sources.json`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/sources/official-sources.json), and each data row carries `doc_url` and `trust`.
111
+ - Last audit against the official docs: 2026-11-17, recorded in [`references/audit-20261117.md`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-payment/references/audit-20261117.md).
112
+ - Self-test: `python3 scripts/test_skill.py` runs 50 checks, 0 failures (run on 2026-11-17).
113
+ - Evals: on the 10 scored questions, Claude answered 10 correctly with the skill and 0 without it. See [`evals/RESULTS.md`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-payment/evals/RESULTS.md).
114
+ - CI runs `scripts/verify-examples.py`, which compares the example code byte for byte with expected values produced by the providers' own SDKs and spec samples ([`tests/vectors/`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/tree/main/tests/vectors)).
115
+
116
+ ## Limits
117
+
118
+ - O'Pay and GoMyPay have no runnable example. The full GoMyPay API specification is not public; you have to request it from GoMyPay.
119
+ - The JKOPAY documentation site did not resolve during the latest audit, so the JKOPAY reference is based on the last saved copy of the official pages.
120
+ - Known gaps and unanswered questions are tracked in [`data/pending.csv`](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/taiwan-payment/data/pending.csv).
121
+ - Rows marked `trust=推論` (recommendations, troubleshooting) are inferred from the official docs. Treat them as advice, not as provider rules.
122
+
123
+ ## Repo layout
124
+
125
+ ```text
126
+ taiwan-payment/
127
+ ├── SKILL.md # instructions Claude reads
128
+ ├── EXAMPLES.md # longer code examples
129
+ ├── references/ # one API reference per provider, plus the audit log
130
+ ├── examples/ # runnable Python clients
131
+ ├── data/ # CSV data for search.py and recommend.py; pending.csv
132
+ ├── scripts/ # search, recommend, tests, number check
133
+ └── evals/ # eval questions, grader and results
134
+ ```
135
+
136
+ ## License & author
137
+
138
+ MIT License. Made by Moksa ([moksaweb.com](https://moksaweb.com)). Part of [Taiwan E-commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit).