199 lines
5.7 KiB
Markdown
199 lines
5.7 KiB
Markdown
# Stripe 支付集成配置指南
|
||
|
||
本文档详细说明如何为 Prmbr 项目配置 Stripe 支付系统，实现订阅管理功能。
|
||
|
||
## 1. Stripe 账户设置
|
||
|
||
### 1.1 创建 Stripe 账户
|
||
1. 访问 [Stripe Dashboard](https://dashboard.stripe.com/)
|
||
2. 注册或登录 Stripe 账户
|
||
3. 完成账户验证（可能需要提供业务信息）
|
||
|
||
### 1.2 获取 API 密钥
|
||
在 Stripe Dashboard 中：
|
||
1. 进入 **Developers** → **API keys**
|
||
2. 复制以下密钥：
|
||
- **Publishable key** (以 `pk_` 开头)
|
||
- **Secret key** (以 `sk_` 开头)
|
||
|
||
## 2. 创建产品和价格
|
||
|
||
### 2.1 创建 Pro 订阅产品
|
||
1. 在 Stripe Dashboard 中，进入 **Products**
|
||
2. 点击 **Add product**
|
||
3. 填写产品信息：
|
||
- **Name**: `Prmbr Pro Plan`
|
||
- **Description**: `Professional plan with advanced features`
|
||
4. 添加价格：
|
||
- **Price**: `$19.90`
|
||
- **Billing period**: `Monthly`
|
||
- **Currency**: `USD`
|
||
5. 保存产品并复制 **Price ID** (以 `price_` 开头)
|
||
|
||
### 2.2 配置产品元数据（可选）
|
||
为产品添加元数据以便识别：
|
||
- `plan_type`: `pro`
|
||
- `features`: `5000_prompts,10_versions,priority_support`
|
||
|
||
## 3. 环境变量配置
|
||
|
||
在项目根目录的 `.env.local` 文件中添加以下环境变量：
|
||
|
||
```bash
|
||
# Stripe 配置
|
||
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your_publishable_key_here"
|
||
STRIPE_SECRET_KEY="sk_test_your_secret_key_here"
|
||
NEXT_PUBLIC_APP_URL="http://localhost:3000"
|
||
|
||
# Webhook 密钥（稍后配置）
|
||
STRIPE_WEBHOOK_SECRET="whsec_your_webhook_secret_here"
|
||
```
|
||
|
||
**注意**: 不再需要 `NEXT_PUBLIC_STRIPE_PRO_PRICE_ID` 环境变量，价格 ID 现在从数据库动态获取。
|
||
|
||
### 3.1 配置 Pro 套餐价格 ID
|
||
|
||
创建 Stripe 价格后，需要在数据库中更新 Pro 套餐的 `stripePriceId` 字段：
|
||
|
||
```sql
|
||
-- 在数据库中更新 Pro 套餐的 Stripe 价格 ID
|
||
UPDATE subscription_plans
|
||
SET "stripePriceId" = 'price_your_actual_pro_price_id_here'
|
||
WHERE name = 'pro';
|
||
```
|
||
|
||
或者使用管理员 API 更新：
|
||
|
||
```bash
|
||
curl -X PUT http://localhost:3000/api/admin/subscription-plans \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"id": "pro",
|
||
"stripePriceId": "price_your_actual_pro_price_id_here"
|
||
}'
|
||
```
|
||
|
||
## 4. Webhook 配置
|
||
|
||
### 4.1 创建 Webhook 端点
|
||
1. 在 Stripe Dashboard 中，进入 **Developers** → **Webhooks**
|
||
2. 点击 **Add endpoint**
|
||
3. 设置端点 URL：
|
||
- **开发环境**: `http://localhost:3000/api/webhooks/stripe`
|
||
- **生产环境**: `https://yourdomain.com/api/webhooks/stripe`
|
||
|
||
### 4.2 选择监听事件
|
||
添加以下事件类型：
|
||
- `customer.subscription.created`
|
||
- `customer.subscription.updated`
|
||
- `customer.subscription.deleted`
|
||
- `invoice.payment_succeeded`
|
||
- `invoice.payment_failed`
|
||
|
||
### 4.3 获取 Webhook 签名密钥
|
||
1. 创建 webhook 后，点击进入详情页面
|
||
2. 在 **Signing secret** 部分，点击 **Reveal** 复制密钥
|
||
3. 将密钥添加到环境变量 `STRIPE_WEBHOOK_SECRET`
|
||
|
||
## 5. 客户门户配置
|
||
|
||
### 5.1 启用客户门户
|
||
1. 在 Stripe Dashboard 中，进入 **Settings** → **Billing** → **Customer portal**
|
||
2. 点击 **Activate** 启用客户门户
|
||
3. 配置门户设置：
|
||
- **Business information**: 填写公司信息
|
||
- **Customer information**: 允许客户更新邮箱和地址
|
||
- **Subscriptions**: 允许客户取消订阅
|
||
- **Payment methods**: 允许客户更新付款方式
|
||
|
||
### 5.2 自定义门户外观
|
||
1. 在 **Branding** 部分上传 Logo
|
||
2. 设置主题颜色以匹配您的品牌
|
||
3. 配置返回 URL: `https://yourdomain.com/subscription`
|
||
|
||
## 6. 测试配置
|
||
|
||
### 6.1 使用测试卡号
|
||
Stripe 提供测试卡号用于开发：
|
||
- **成功支付**: `4242 4242 4242 4242`
|
||
- **需要验证**: `4000 0025 0000 3155`
|
||
- **被拒绝**: `4000 0000 0000 0002`
|
||
|
||
### 6.2 测试订阅流程
|
||
1. 启动开发服务器: `npm run dev`
|
||
2. 访问价格页面: `http://localhost:3000/pricing`
|
||
3. 点击 "Upgrade to Pro" 按钮
|
||
4. 使用测试卡号完成支付
|
||
5. 验证用户订阅状态是否正确更新
|
||
|
||
## 7. 生产环境部署
|
||
|
||
### 7.1 切换到生产密钥
|
||
1. 在 Stripe Dashboard 右上角关闭 **Test mode**
|
||
2. 获取生产环境的 API 密钥
|
||
3. 更新环境变量为生产密钥
|
||
|
||
### 7.2 更新 Webhook URL
|
||
1. 创建新的生产环境 webhook 端点
|
||
2. 使用生产域名: `https://yourdomain.com/api/webhooks/stripe`
|
||
3. 更新 `STRIPE_WEBHOOK_SECRET` 为生产密钥
|
||
|
||
### 7.3 验证配置
|
||
- 确保所有环境变量正确设置
|
||
- 测试完整的订阅和取消流程
|
||
- 验证 webhook 事件正常接收和处理
|
||
|
||
## 8. 常见问题
|
||
|
||
### 8.1 Webhook 验证失败
|
||
- 检查 `STRIPE_WEBHOOK_SECRET` 是否正确
|
||
- 确保 webhook URL 可以从外网访问
|
||
- 验证请求头中的签名
|
||
|
||
### 8.2 订阅状态不同步
|
||
- 检查 webhook 事件是否正常接收
|
||
- 查看服务器日志中的错误信息
|
||
- 确保数据库连接正常
|
||
|
||
### 8.3 支付失败
|
||
- 检查 Stripe 密钥是否正确
|
||
- 验证产品和价格 ID 是否匹配
|
||
- 确保客户信息完整
|
||
|
||
## 9. 安全注意事项
|
||
|
||
1. **密钥安全**：
|
||
- 永远不要在客户端代码中暴露 Secret Key
|
||
- 使用环境变量存储敏感信息
|
||
- 定期轮换 API 密钥
|
||
|
||
2. **Webhook 安全**：
|
||
- 始终验证 webhook 签名
|
||
- 使用 HTTPS 端点
|
||
- 实现幂等性处理
|
||
|
||
3. **数据保护**：
|
||
- 不要存储完整的信用卡信息
|
||
- 遵循 PCI DSS 合规要求
|
||
- 定期备份订阅数据
|
||
|
||
## 10. 监控和日志
|
||
|
||
### 10.1 Stripe Dashboard 监控
|
||
- 定期检查支付状态
|
||
- 监控失败的支付和订阅
|
||
- 查看客户活动日志
|
||
|
||
### 10.2 应用程序日志
|
||
- 记录所有 Stripe API 调用
|
||
- 监控 webhook 处理状态
|
||
- 设置错误告警
|
||
|
||
---
|
||
|
||
配置完成后，您的应用程序将具备完整的订阅管理功能，包括：
|
||
- 用户订阅 Pro 计划
|
||
- 自动处理订阅状态变更
|
||
- 客户自助管理订阅
|
||
- 安全的支付处理
|