taiwan-payment-skill 1.0.0

package/assets/taiwan-payment/README.md

@@ -0,0 +1,306 @@
+# Taiwan Payment Gateway Integration Toolkit
+
+**Professional payment gateway integration solution for Taiwan market**
+
+Supporting ECPay (綠界科技), NewebPay (藍新金流), and PAYUNi (統一金流) with comprehensive API documentation, intelligent tools, and production-ready code examples.
+
+---
+
+## Overview
+
+This toolkit provides enterprise-grade integration capabilities for Taiwan's major payment gateways, featuring:
+
+- **Complete API Documentation**: Detailed specifications for all three providers
+- **Intelligent Search Engine**: BM25-powered search across 7 domains (API docs, error codes, field mappings, payment methods)
+- **Smart Recommendation System**: AI-driven provider selection based on business requirements
+- **Production-Ready Examples**: 9 comprehensive TypeScript/Python implementations
+- **Data-Driven Architecture**: 7 CSV datasets for easy maintenance and updates
+- **Multi-Platform Support**: Compatible with 14 AI coding assistants
+
+---
+
+## Supported Payment Gateways
+
+| Provider | Encryption | API Style | Market Share | Status |
+|----------|-----------|-----------|--------------|--------|
+| **ECPay (綠界科技)** | SHA256 | Form POST | High | ✅ Full Support |
+| **NewebPay (藍新金流)** | AES-256-CBC + SHA256 | Form POST + AES | High | ✅ Full Support |
+| **PAYUNi (統一金流)** | AES-256-GCM + SHA256 | RESTful JSON | Medium | ✅ Full Support |
+
+### Technical Comparison
+
+| Feature | ECPay | NewebPay | PAYUNi |
+|---------|-------|----------|---------|
+| **Encryption Method** | URL Encode + SHA256 | Dual-layer (AES-256-CBC + SHA256) | AES-256-GCM + SHA256 |
+| **Content Type** | application/x-www-form-urlencoded | application/x-www-form-urlencoded | application/json |
+| **Payment Methods** | 11 types (including BNPL, TWQR) | 13 types (including LINE Pay, Apple Pay) | 8 types (including AFTEE, iCash) |
+| **API Design** | Traditional Form POST | MPG Integration, Form POST | Modern RESTful JSON |
+| **Best For** | High-volume e-commerce, Traditional industries | Multi-payment scenarios, Mobile apps | API-first startups, Modern tech stacks |
+
+---
+
+## Installation
+
+### NPM Global Installation
+
+```bash
+npm install -g taiwan-payment-skill
+```
+
+### Initialize in Project
+
+```bash
+# Auto-detect AI assistant
+taiwan-payment init
+
+# Specify AI assistant type
+taiwan-payment init --ai claude      # Claude Code
+taiwan-payment init --ai cursor      # Cursor
+taiwan-payment init --ai windsurf    # Windsurf
+```
+
+### Supported AI Platforms (14)
+
+Claude Code · Cursor · Windsurf · GitHub Copilot · Antigravity · Kiro · Codex · Qoder · Roo Code · Gemini CLI · Trae · OpenCode · Continue · CodeBuddy
+
+---
+
+## Intelligent Tools
+
+### 1. BM25 Search Engine
+
+Fast semantic search across payment gateway documentation and error codes.
+
+```bash
+# Search error codes
+python scripts/search.py "10100058" --domain error
+
+# Search payment methods
+python scripts/search.py "信用卡" --domain payment_method
+
+# Search field mappings
+python scripts/search.py "MerchantTradeNo" --domain field
+
+# JSON output
+python scripts/search.py "ATM" --format json
+```
+
+**Search Domains:**
+- `provider` - Provider comparison
+- `operation` - API endpoints
+- `error` - Error code lookup
+- `field` - Field name mappings
+- `payment_method` - Payment method specifications
+- `troubleshoot` - Troubleshooting guides
+- `reasoning` - Recommendation logic
+
+### 2. Smart Recommendation System
+
+AI-powered provider recommendation based on business requirements.
+
+```bash
+# High-volume e-commerce
+python scripts/recommend.py "高交易量 電商 穩定"
+# → Recommends ECPay (highest market share, proven stability)
+
+# Multi-payment requirements
+python scripts/recommend.py "多元支付 LINE Pay Apple Pay"
+# → Recommends NewebPay (supports 13 payment methods)
+
+# API-first design
+python scripts/recommend.py "API RESTful JSON"
+# → Recommends PAYUNi (modern RESTful design)
+```
+
+### 3. Connection Testing Tool
+
+Verify API connectivity and credentials.
+
+```bash
+# Test specific provider
+python scripts/test_payment.py ecpay
+python scripts/test_payment.py newebpay
+python scripts/test_payment.py payuni
+
+# Test all providers
+python scripts/test_payment.py all
+```
+
+---
+
+## Architecture
+
+```
+taiwan-payment/
+├── SKILL.md                        # Main documentation (857 lines)
+├── EXAMPLES.md                     # Code examples (1425 lines)
+├── references/                     # API specifications
+│   ├── ECPAY_PAYMENT_REFERENCE.md
+│   ├── NEWEBPAY_PAYMENT_REFERENCE.md
+│   └── PAYUNI_PAYMENT_REFERENCE.md
+├── scripts/                        # Python intelligent tools
+│   ├── core.py                     # BM25 search engine (311 lines)
+│   ├── recommend.py                # Recommendation system (373 lines)
+│   ├── search.py                   # Search CLI (150+ lines)
+│   └── test_payment.py             # Connection testing (359 lines)
+└── data/                           # Data-driven architecture (7 CSV files)
+    ├── providers.csv               # Provider details
+    ├── operations.csv              # API operations
+    ├── error-codes.csv             # Error code mappings
+    ├── field-mappings.csv          # Field name mappings
+    ├── payment-methods.csv         # Payment method specs
+    ├── reasoning.csv               # Recommendation rules (30+ scenarios)
+    └── troubleshooting.csv         # Common issues (16 cases)
+```
+
+---
+
+## Payment Methods
+
+### Credit Card
+- One-time payment, Installments (3/6/12/18/24/30 periods)
+- Recurring billing, Credit card tokenization
+
+### E-Wallets
+- Apple Pay, Google Pay, Samsung Pay
+- LINE Pay, Taiwan Pay
+
+### Bank Transfer
+- WebATM, Virtual account (ATM)
+
+### Convenience Store
+- CVS payment code, CVS barcode
+
+### Others
+- TWQR, BNPL (Buy Now Pay Later), AFTEE, iCash
+
+---
+
+## Code Examples
+
+### ECPay Credit Card Payment
+
+```typescript
+import { createPayment } from './ecpay-service';
+
+const order = {
+  merchantId: '3002607',
+  orderId: `ORDER${Date.now()}`,
+  amount: 1050,
+  description: 'Product Purchase',
+  returnUrl: 'https://example.com/callback',
+  paymentMethod: 'Credit'
+};
+
+const form = await createPayment(order);
+// Returns HTML form ready for submission
+```
+
+### NewebPay MPG Integration
+
+```typescript
+import { createPayment } from './newebpay-service';
+
+const order = {
+  merchantId: 'YOUR_MERCHANT_ID',
+  orderId: `ORDER${Date.now()}`,
+  amount: 2500,
+  description: 'E-commerce Order',
+  returnUrl: 'https://example.com/notify',
+  paymentMethod: 'CREDIT,VACC,CVS' // Multiple methods
+};
+
+const form = await createPayment(order);
+```
+
+### PAYUNi RESTful API
+
+```typescript
+import axios from 'axios';
+import { encryptPayUni } from './encryption';
+
+const order = {
+  MerID: 'YOUR_MERCHANT_ID',
+  MerTradeNo: `ORDER${Date.now()}`,
+  TradeAmt: 3000,
+  ProdDesc: 'Subscription Service',
+  ReturnURL: 'https://example.com/callback',
+  PayType: 'Credit'
+};
+
+const { encryptInfo, hashInfo } = encryptPayUni(order);
+const response = await axios.post('https://sandbox-api.payuni.com.tw/api/upp', {
+  MerID: order.MerID,
+  EncryptInfo: encryptInfo,
+  HashInfo: hashInfo
+});
+```
+
+---
+
+## Data-Driven Architecture
+
+All business logic is stored in CSV files for easy maintenance:
+
+- **providers.csv**: Provider configurations (encryption, test accounts, API endpoints)
+- **operations.csv**: API operations (create, query, refund, recurring)
+- **error-codes.csv**: Error code mappings with solutions
+- **field-mappings.csv**: Field name translations across providers
+- **payment-methods.csv**: Payment method specifications
+- **reasoning.csv**: Recommendation rules (30+ business scenarios)
+- **troubleshooting.csv**: Common issues and solutions (16 cases)
+
+---
+
+## Development Requirements
+
+- **Node.js** >= 18.0.0 (CLI tool)
+- **Python** >= 3.x (intelligent scripts, no external dependencies)
+
+---
+
+## Documentation
+
+- [SKILL.md](./SKILL.md) - Complete skill documentation (857 lines)
+- [EXAMPLES.md](./EXAMPLES.md) - 9 production-ready code examples (1425 lines)
+- [CLAUDE.md](./CLAUDE.md) - Development guide for Claude Code
+
+### API References
+
+- [ECPay Payment API](./references/ECPAY_PAYMENT_REFERENCE.md)
+- [NewebPay Payment API](./references/NEWEBPAY_PAYMENT_REFERENCE.md)
+- [PAYUNi Payment API](./references/PAYUNI_PAYMENT_REFERENCE.md)
+
+---
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT)
+
+---
+
+## Related Projects
+
+- [taiwan-invoice-skill](https://github.com/Moksa1123/taiwan-invoice) - Taiwan E-Invoice integration
+- [taiwan-logistics-skill](https://github.com/Moksa1123/taiwan-logistics) - Taiwan logistics integration
+
+---
+
+## Support
+
+- **Official Documentation**: See `references/` directory
+- **Technical Support**:
+  - ECPay: techsupport@ecpay.com.tw
+  - NewebPay: 02-2655-8938
+  - PAYUNi: 02-2747-5100
+
+---
+
+<p align="center">
+  <sub>Professional toolkit by <strong>Moksa</strong></sub><br>
+  <sub>service@moksaweb.com</sub>
+</p>
+
+<p align="center">
+  <sub>Last updated: 2026-01-29</sub>
+</p>