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