tw-payment-integration
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTaiwan Payment Integration
台湾地区支付集成
Framework
框架
IRON LAW: Support At Least 3 Payment Methods in Taiwan
Taiwan consumers expect choice. Credit card alone misses ~40% of potential
buyers. The minimum viable payment mix for Taiwan e-commerce:
1. Credit card (信用卡)
2. ATM/bank transfer (ATM 虛擬帳號)
3. Convenience store payment (超商代碼/超商取貨付款)
Adding LINE Pay and Apple Pay captures another 10-15%.IRON LAW: Support At Least 3 Payment Methods in Taiwan
台湾消费者期望有多种选择。仅支持信用卡会错失约40%的潜在买家。台湾电商的最低可行支付组合：
1. Credit card (信用卡)
2. ATM/bank transfer (ATM 虛擬帳號)
3. Convenience store payment (超商代碼/超商取貨付款)
添加LINE Pay和Apple Pay可覆盖额外10-15%的用户。Taiwan Payment Landscape
台湾地区支付格局
| Method | Market Share | User Profile | Settlement Time |
|---|---|---|---|
| Credit/Debit card | ~45% | All ages, higher spending | T+1 to T+7 |
| ATM virtual account | ~15% | Price-sensitive, no credit card | Instant to T+1 |
| Convenience store (超商代碼) | ~10% | Students, cash-preferred | T+1 to T+3 |
| LINE Pay | ~12% | LINE users (95% of Taiwan) | T+1 to T+7 |
| Apple Pay / Google Pay | ~5% | Mobile-first users | T+1 to T+7 |
| 超商取貨付款 (COD at store) | ~8% | Low trust, want to see product | Upon pickup + T+3 |
| JKoPay / 街口 | ~3% | Younger demographic | T+1 |
| 支付方式 | 市场份额 | 用户画像 | 结算周期 |
|---|---|---|---|
| 信用卡/借记卡 | ~45% | 全年龄段，消费能力较高 | T+1至T+7 |
| ATM虚拟账户 | ~15% | 对价格敏感，无信用卡 | 即时至T+1 |
| 便利店（超商代碼） | ~10% | 学生群体，偏好现金支付 | T+1至T+3 |
| LINE Pay | ~12% | LINE用户（覆盖台湾95%人群） | T+1至T+7 |
| Apple Pay / Google Pay | ~5% | 移动优先用户 | T+1至T+7 |
| 超商取貨付款 (COD at store) | ~8% | 信任度低，希望先看到商品 | 取货后+T+3 |
| JKoPay / 街口 | ~3% | 年轻群体 | T+1 |
Payment Service Providers (PSP)
支付服务提供商（PSP）
| PSP | Strengths | Pricing | Best For |
|---|---|---|---|
| 綠界 (ECPay) | Most comprehensive (credit card, ATM, CVS, 超取), largest market share | 2.75% credit card, NT$15/ATM txn | General e-commerce, startups |
| 藍新 (NewebPay) | Good API design, modern dashboard | 2.5-2.8% credit card | SaaS, subscription businesses |
| TapPay | Mobile-first, Apple Pay/Google Pay/LINE Pay integration | 2.5-2.8% credit card | Mobile apps, in-app purchases |
| PayNow | Easy setup, no monthly fee | 2.75% credit card | Low-volume, new businesses |
| Stripe | International, excellent API | 3.4% + NT$10 per txn | Cross-border, international focus |
| PSP | 优势 | 定价 | 适用场景 |
|---|---|---|---|
| 綠界 (ECPay) | 覆盖最全面（信用卡、ATM、便利店、超取），市场份额最高 | 信用卡2.75%，ATM交易每笔NT$15 | 通用电商、初创企业 |
| 藍新 (NewebPay) | API设计优秀，控制台界面现代化 | 信用卡2.5-2.8% | SaaS、订阅类业务 |
| TapPay | 移动优先，支持Apple Pay/Google Pay/LINE Pay集成 | 信用卡2.5-2.8% | 移动应用、应用内购买 |
| PayNow | 搭建简单，无月费 | 信用卡2.75% | 低交易量、新成立商家 |
| Stripe | 国际化，API体验极佳 | 每笔3.4% + NT$10 | 跨境业务、国际化需求 |
Integration Flow (Standard)
标准集成流程
1. Customer clicks "Pay" on your site
2. Your server creates an order → sends to PSP API
3. PSP returns a payment page URL (or token for inline)
4. Customer completes payment on PSP-hosted page
5. PSP sends callback (webhook) to your server with result
6. Your server verifies the callback signature
7. Update order status → show confirmation to customer1. 客户在您的网站点击“支付”
2. 您的服务器创建订单 → 发送至PSP API
3. PSP返回支付页面URL（或内嵌支付所需的token）
4. 客户在PSP托管页面完成支付
5. PSP向您的服务器发送回调（webhook）告知支付结果
6. 您的服务器验证回调签名
7. 更新订单状态 → 向客户展示支付确认信息Key API Concepts
核心API概念
| Concept | What It Is |
|---|---|
| MerchantID | Your account identifier with the PSP |
| HashKey / HashIV | Secret keys for signature verification |
| TradeNo | Your order ID (must be unique per transaction) |
| PaymentType | Credit, ATM, CVS, WebATM, etc. |
| Callback URL | Webhook endpoint PSP calls after payment |
| Return URL | Page to redirect customer after payment |
| CheckMacValue | HMAC signature to verify data integrity |
| 概念 | 含义 |
|---|---|
| MerchantID | 您在PSP平台的账户标识 |
| HashKey / HashIV | 用于签名验证的密钥 |
| TradeNo | 您的订单ID（每笔交易必须唯一） |
| PaymentType | 支付类型：信用卡、ATM、便利店、WebATM等 |
| Callback URL | PSP支付完成后调用的Webhook端点 |
| Return URL | 支付完成后跳转至的客户页面 |
| CheckMacValue | 用于验证数据完整性的HMAC签名 |
Refund Handling
退款处理
| Method | Refund Capability | Timing |
|---|---|---|
| Credit card | Full or partial refund via API | 1-7 business days |
| ATM | Cannot auto-refund — must wire transfer back | Manual, 3-7 days |
| CVS payment | Cannot auto-refund — must wire transfer back | Manual, 3-7 days |
| LINE Pay | Full refund via API | 1-3 business days |
| 支付方式 | 退款能力 | 处理时效 |
|---|---|---|
| 信用卡 | 支持通过API全额或部分退款 | 1-7个工作日 |
| ATM | 无法自动退款——需手动转账退回 | 人工处理，3-7天 |
| 便利店支付 | 无法自动退款——需手动转账退回 | 人工处理，3-7天 |
| LINE Pay | 支持通过API全额退款 | 1-3个工作日 |
Security Requirements
安全要求
| Requirement | What to Do |
|---|---|
| SSL/TLS | All payment pages must be HTTPS |
| 3D Secure | Enable 3DS 2.0 for credit card fraud reduction |
| PCI DSS | If handling raw card data, need PCI compliance. Using PSP-hosted payment page avoids this. |
| Tokenization | Store payment tokens, never raw card numbers |
| Webhook verification | Always verify CheckMacValue signature before processing callbacks |
| Idempotency | Handle duplicate callbacks gracefully (PSP may retry) |
| 要求 | 实施要点 |
|---|---|
| SSL/TLS | 所有支付页面必须采用HTTPS协议 |
| 3D Secure | 启用3DS 2.0以降低信用卡欺诈风险 |
| PCI DSS | 若处理原始卡数据，需符合PCI合规要求。使用PSP托管支付页面可规避此要求 |
| Tokenization | 存储支付令牌，绝不存储原始卡号 |
| Webhook验证 | 处理回调前务必验证CheckMacValue签名 |
| 幂等性 | 优雅处理重复回调（PSP可能重试） |
Output Format
输出格式
markdown
undefinedmarkdown
undefinedPayment Integration Plan: {Business}
支付集成方案: {Business}
Payment Method Selection
支付方式选择
| Method | Include? | PSP | Rationale |
|---|---|---|---|
| Credit card | Y/N | {provider} | {why} |
| ATM | Y/N | ... | ... |
| CVS | Y/N | ... | ... |
| LINE Pay | Y/N | ... | ... |
| 支付方式 | 是否接入 | PSP服务商 | 理由 |
|---|---|---|---|
| 信用卡 | 是/否 | {provider} | {why} |
| ATM | 是/否 | ... | ... |
| 便利店 | 是/否 | ... | ... |
| LINE Pay | 是/否 | ... | ... |
PSP Selection
PSP服务商选择
- Provider: {name}
- Pricing: {rate}
- Rationale: {why this provider}
- 提供商: {name}
- 定价: {rate}
- 理由: {why this provider}
Integration Plan
集成计划
| Phase | Task | Timeline |
|---|---|---|
| 1 | Apply for PSP merchant account | 1-2 weeks |
| 2 | Develop payment flow (sandbox) | 1-2 weeks |
| 3 | Implement webhook handler | 1 week |
| 4 | Security review (SSL, signature verification) | 2-3 days |
| 5 | Production testing with real transactions | 1 week |
| 6 | Go-live | 1 day |
| 阶段 | 任务 | 时间周期 |
|---|---|---|
| 1 | 申请PSP商户账户 | 1-2周 |
| 2 | 开发支付流程（沙箱环境） | 1-2周 |
| 3 | 实现Webhook处理器 | 1周 |
| 4 | 安全审核（SSL、签名验证） | 2-3天 |
| 5 | 生产环境真实交易测试 | 1周 |
| 6 | 正式上线 | 1天 |
Refund Process
退款流程
{How each payment method handles refunds}
undefined{各支付方式的退款处理说明}
undefinedGotchas
注意事项
- PSP application takes time: Merchant account approval can take 1-3 weeks. Apply early. Credit card processing requires additional documentation (company registration, bank account proof).
- ATM and CVS refunds are manual: Unlike credit cards, ATM and convenience store payments cannot be auto-refunded. You need the customer's bank account to wire money back. Build this into your CS process.
- Webhook reliability: PSP callbacks can be delayed or duplicated. Build idempotent handlers and implement a reconciliation job that checks PSP records against your database daily.
- Foreign credit cards: Not all Taiwan PSPs support foreign credit cards well. If you have international customers, test with non-Taiwan cards or use Stripe.
- Recurring payments (subscription): 綠界 and 藍新 support recurring billing, but you need the customer's explicit consent and must handle card expiration/update flows.
- PSP账户申请耗时: 商户账户审核可能需要1-3周，建议提前申请。信用卡收款需额外提交证明文件（公司注册资料、银行账户证明）。
- ATM和便利店退款需人工操作: 与信用卡不同，ATM和便利店支付无法自动退款。您需要获取客户的银行账户信息进行转账退回，需将此流程纳入客户服务体系。
- Webhook可靠性: PSP回调可能延迟或重复。需构建幂等处理器，并实现每日对账任务，核对PSP记录与您的数据库数据。
- 境外信用卡支持: 并非所有台湾PSP都能良好支持境外信用卡。若服务国际客户，请测试非台湾地区卡片或使用Stripe。
- ** recurring payments (订阅)**: 綠界和藍新支持 recurring billing，但需获得客户明确同意，并处理卡片过期/更新流程。
References
参考资料
- For 綠界 API integration guide, see
references/ecpay-api.md - For PCI DSS compliance checklist, see
references/pci-checklist.md
- 綠界API集成指南，请查看
references/ecpay-api.md - PCI DSS合规检查表，请查看
references/pci-checklist.md