🪙 QuantMesh 加密货币支付系统总结

📊 实施概览

实施日期: 2025-12-30 状态: ✅ 完成并可投入使用

由于 Stripe 等传统支付方式接入复杂,且不符合加密货币做市商的项目定位,我们实现了完整的加密货币支付系统。

🎯 核心功能

1. 双支付方式

方式	特点	适用场景
Coinbase Commerce	自动确认、支持多币种、有支付页面	所有用户 (推荐)
直接钱包支付	无第三方、更私密、需手动确认	注重隐私的用户

2. 支持的加密货币

✅ BTC (Bitcoin)
✅ ETH (Ethereum)
✅ USDT (Tether, ERC20)
✅ USDC (USD Coin, ERC20)

💡 推荐: USDT/USDC (稳定币,价格无波动)

3. 完整的支付流程

用户选择套餐 → 选择支付方式 → 创建支付订单 
→ 用户转账 → 区块链确认 → 自动/手动确认 
→ 激活订阅 → 发送通知

📁 新增文件

核心代码

saas/crypto_payment_service.go (430 行)
- 加密货币支付服务
- Coinbase Commerce 集成
- 直接钱包支付
- Webhook 处理
- 数据库操作
web/api_crypto_payment.go (280 行)
- RESTful API 端点
- 支付创建、查询、确认
- 交易哈希提交
- 支付历史查询

文档

docs/CRYPTO_PAYMENT_GUIDE.md
- 用户支付指南
- 详细操作步骤
- 常见问题解答
docs/CRYPTO_PAYMENT_SETUP.md
- 部署配置指南
- 技术实现细节
- 监控和维护
docs/CRYPTO_PAYMENT_QUICKSTART.md
- 5 分钟快速开始
- 两种方案对比
- 集成示例代码

配置和脚本

.env.crypto.example
- 环境变量配置示例
- Coinbase API Key
- 钱包地址配置
scripts/init_crypto_payments.sql
- 数据库初始化脚本
- 创建表和索引
- 触发器设置
test_crypto_payment.sh
- 自动化测试脚本
- 测试所有 API 端点
- 支持多币种和多套餐

🔌 API 端点

公开端点

GET  /api/payment/crypto/currencies        # 获取支持的加密货币

需要认证

POST /api/payment/crypto/coinbase/create   # 创建 Coinbase 支付
POST /api/payment/crypto/direct/create     # 创建直接钱包支付
GET  /api/payment/crypto/list              # 查看支付历史
GET  /api/payment/crypto/:id               # 查看支付状态
POST /api/payment/crypto/:id/submit-tx     # 提交交易哈希

管理员端点

POST /api/payment/crypto/:id/confirm       # 确认支付

Webhook

POST /api/payment/crypto/webhook/coinbase  # Coinbase Webhook

💾 数据库设计

crypto_payments 表

CREATE TABLE crypto_payments (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    plan VARCHAR(50) NOT NULL,
    amount DECIMAL(10, 2) NOT NULL,           -- USD 金额
    currency VARCHAR(3) DEFAULT 'USD',
    crypto_currency VARCHAR(10),              -- BTC/ETH/USDT/USDC
    crypto_amount DECIMAL(20, 8),             -- 加密货币金额
    payment_method VARCHAR(20) NOT NULL,      -- coinbase/direct
    status VARCHAR(20) NOT NULL,              -- pending/completed/expired
    charge_id VARCHAR(255),                   -- Coinbase Charge ID
    payment_address TEXT,                     -- 支付地址或 URL
    transaction_hash VARCHAR(255),            -- 交易哈希
    expires_at TIMESTAMP,
    completed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

索引

idx_crypto_payments_user_id - 用户查询
idx_crypto_payments_status - 状态筛选
idx_crypto_payments_charge_id - Webhook 查询
idx_crypto_payments_expires_at - 过期清理

🚀 部署步骤

方案 A: Coinbase Commerce (推荐)

# 1. 注册 Coinbase Commerce
# 访问 https://commerce.coinbase.com

# 2. 配置环境变量
cp .env.crypto.example .env.crypto
vim .env.crypto  # 填入 API Key

# 3. 初始化数据库
psql -U postgres -d quantmesh -f scripts/init_crypto_payments.sql

# 4. 启动服务
go run main.go

# 5. 配置 Webhook
# 在 Coinbase 后台配置: https://your-domain.com/api/payment/crypto/webhook/coinbase

# 6. 测试
./test_crypto_payment.sh

方案 B: 直接钱包支付 (5 分钟)

# 1. 配置钱包地址
# 编辑 saas/crypto_payment_service.go
# 或设置环境变量

# 2. 初始化数据库
psql -U postgres -d quantmesh -f scripts/init_crypto_payments.sql

# 3. 启动服务
go run main.go

# 4. 测试
./test_crypto_payment.sh

💰 商业价值

对用户的优势

✅ 便捷性

无需信用卡或银行账户
全球通用,无地域限制

✅ 低成本

交易费用低 (Coinbase 1%, 直接支付仅 Gas 费)
无汇率损失

✅ 隐私保护

无需 KYC
匿名支付 (直接钱包)

✅ 快速到账

10-30 分钟确认
立即激活订阅

对项目的优势

✅ 定位契合

加密货币做市商使用加密货币支付,天然契合
增强品牌认知度

✅ 降低门槛

无需复杂的支付网关接入
无需 KYC/AML 合规

✅ 扩大市场

覆盖全球加密货币用户
无地域限制

✅ 降低成本

Coinbase 手续费 1% (Stripe 2.9% + $0.30)
直接支付无手续费

✅ 资金安全

资金直接到账
无第三方托管风险

收入预测

套餐	月费	预计用户 (第一年)	年收入
Starter	$49	200	$117,600
Professional	$199	80	$190,080
Enterprise	$999	10	$119,880
总计	-	290	$427,560

增长预期:

第一年: $427,560 (加密货币支付占 70%)
第二年: $1,200,000 (增长 180%)
第三年: $3,000,000 (增长 150%)

🔒 安全措施

1. Webhook 签名验证

func verifyCoinbaseSignature(payload []byte, signature string) bool {
    mac := hmac.New(sha256.New, []byte(webhookSecret))
    mac.Write(payload)
    expectedSignature := hex.EncodeToString(mac.Sum(nil))
    return signature == expectedSignature
}

2. 支付金额验证

// 允许 1% 误差 (汇率波动)
if payment.CryptoAmount < expectedAmount * 0.99 {
    return errors.New("支付金额不足")
}

3. 防重放攻击

if payment.Status == "completed" {
    return errors.New("支付已完成,请勿重复处理")
}

4. 支付过期机制

Coinbase: 1 小时自动过期
直接支付: 24 小时自动过期

5. 区块确认要求

BTC: 3 个确认
ETH/USDT/USDC: 12 个确认

📈 监控指标

关键指标

支付成功率

SELECT 
    COUNT(CASE WHEN status = 'completed' THEN 1 END) * 100.0 / COUNT(*) as success_rate
FROM crypto_payments
WHERE created_at > NOW() - INTERVAL '30 days';

平均确认时间

SELECT 
    AVG(EXTRACT(EPOCH FROM (completed_at - created_at)) / 60) as avg_minutes
FROM crypto_payments
WHERE status = 'completed';

各币种占比

SELECT 
    crypto_currency,
    COUNT(*) as count,
    SUM(amount) as total_usd
FROM crypto_payments
WHERE status = 'completed'
GROUP BY crypto_currency;

收入统计

SELECT 
    DATE_TRUNC('month', completed_at) as month,
    COUNT(*) as payments,
    SUM(amount) as revenue
FROM crypto_payments
WHERE status = 'completed'
GROUP BY month
ORDER BY month DESC;

🧪 测试

自动化测试

# 运行完整测试
./test_crypto_payment.sh

# 测试特定功能
curl -X POST http://localhost:8080/api/payment/crypto/direct/create \
  -H "Content-Type: application/json" \
  -d '{"plan":"professional","email":"test@example.com","crypto_currency":"USDT"}'

测试覆盖

✅ 创建 Coinbase 支付
✅ 创建直接钱包支付
✅ 查询支付状态
✅ 提交交易哈希
✅ 确认支付
✅ 查看支付历史
✅ 多币种测试
✅ 多套餐测试

📚 文档

文档	用途	受众
`CRYPTO_PAYMENT_GUIDE.md`	用户支付指南	终端用户
`CRYPTO_PAYMENT_SETUP.md`	部署配置指南	开发者/运维
`CRYPTO_PAYMENT_QUICKSTART.md`	5 分钟快速开始	开发者
`CRYPTO_PAYMENT_SUMMARY.md`	项目总结 (本文档)	项目经理

🎯 下一步行动

立即可做

✅ 测试系统
```
./test_crypto_payment.sh
```
✅ 配置钱包地址
- 编辑 saas/crypto_payment_service.go
- 或设置环境变量

✅ 初始化数据库

psql -U postgres -d quantmesh -f scripts/init_crypto_payments.sql

可选配置

⭐ 注册 Coinbase Commerce (推荐)
- 访问 https://commerce.coinbase.com
- 获取 API Key
- 配置 Webhook
⭐ 集成汇率 API
- 使用 CoinGecko API (免费)
- 实时更新汇率
⭐ 添加邮件通知
- 支付成功通知
- 支付失败通知

生产部署

🚀 部署到生产环境
- 配置 SSL 证书
- 设置 Webhook URL
- 启用签名验证
🚀 监控和告警
- 设置支付失败告警
- 监控支付成功率
- 跟踪收入指标

✨ 总结

实施成果

✅ 完整的加密货币支付系统

2 种支付方式
4 种加密货币
8 个 API 端点
完整的文档和测试

✅ 即插即用

5 分钟快速部署 (直接钱包)
15 分钟完整部署 (Coinbase)

✅ 生产就绪

完善的错误处理
安全的 Webhook 验证
自动化测试脚本

技术亮点

🎯 架构设计

清晰的分层架构
易于扩展和维护

🎯 安全性

Webhook 签名验证
防重放攻击
支付金额验证

🎯 可靠性

自动过期清理
区块确认机制
完善的日志记录

商业价值

💰 降低成本

手续费从 2.9% 降至 1% (或 0%)
无需 KYC/AML 合规成本

💰 扩大市场

覆盖全球加密货币用户
无地域限制

💰 增强品牌

与项目定位契合
提升用户信任度

📞 支持

如有问题,请联系:

🎉 恭喜!加密货币支付系统已完成并可投入使用!

FilesExpand file tree

CRYPTO_PAYMENT_SUMMARY.md

Latest commit

History