payment

添加支付功能

帮用户集成在线支付，实现收款。

步骤

1. 了解需求

问题 1：支付类型

你需要什么类型的支付？

• 一次性付款（买商品、买服务）
• 订阅/会员（按月/按年收费）
• 两者都要

问题 2：定价

价格是多少？如果是订阅，月费和年费分别是多少？

问题 3：目标客户地区

客户主要在哪里？这决定了支付方式的选择。

2. 选择支付服务商

根据需求推荐：

服务商	适用场景	特点
Stripe	国际客户，需要灵活定制	功能最全，开发者体验好，需自行处理税务
LemonSqueezy	SaaS/数字产品	自动处理全球销售税，API 更简单，适合独立开发者
Paddle	SaaS 订阅为主	作为 Merchant of Record 处理税务+发票，合规省心

注意：如果客户在中国大陆，Stripe 对国内用户支付支持有限。建议额外集成支付宝/微信支付（可通过 Stripe 的 Alipay/WeChat Pay 支付方式，或直接对接支付宝开放平台）。

不确定就用 Stripe（生态最大，文档最全）。

3. 配置支付服务

• 安装 SDK — 按所选服务商安装对应的官方库
• 配置环境变量 — Secret Key 和 Publishable Key，添加到 .env.example
• 提示用户去服务商官网注册账号，获取测试模式的 API Key

4. 生成支付代码

后端：

• 创建 Checkout Session 接口
• Webhook 处理（支付成功、订阅变更、退款）
• 验证 Webhook 签名（见下方安全要求）

前端：

• 定价页面（价格卡片 + 购买按钮）
• 跳转到 Checkout 页面
• 支付成功/取消回调页面

订阅（如果需要）：

• 创建 Product 和 Price 对象
• 订阅管理（升级、降级、取消）
• 用户订阅状态查询和权限控制

5. Webhook 安全（必做）

Webhook 是支付系统的核心通信通道，必须做好安全防护：

• 始终验证签名 — 用服务商提供的 Webhook Secret 验证每个请求的签名，拒绝签名不匹配的请求
• 使用 HTTPS 端点 — Webhook URL 必须是 HTTPS
• 实现幂等处理 — 同一事件可能被重复投递，用事件 ID 去重，避免重复发货或重复计费
• 返回 200 状态码 — 即使业务处理失败也先返回 200，把失败的事件放入重试队列。否则服务商会不断重试

6. 测试

使用测试卡号完成端到端验证（Stripe 测试卡：4242 4242 4242 4242，任意未来日期，任意 CVC）：

• 完成一次成功支付
• 用 Stripe CLI 或服务商工具触发 Webhook 事件，确认处理正确
• 测试支付失败场景（卡号 4000 0000 0000 0002）

支付功能已集成，测试模式验证正常。 上线前：切换到生产模式 API Key，配置生产 Webhook 端点。

遇到问题

• Webhook 收不到事件 — 本地开发时需要用 Stripe CLI (stripe listen --forward-to localhost:端口/webhook) 转发事件。部署后确认 Webhook URL 在服务商后台已正确配置且状态为 Active
• 测试模式和生产模式混淆 — 测试 Key 以 sk_test_ 开头，生产 Key 以 sk_live_ 开头。两套 Key 的数据完全隔离。常见错误：用生产 Key 查测试订单，或反过来
• 货币问题 — Stripe 金额单位是"分"（cents），100 = 1 美元。如果显示金额异常，检查是否漏乘或多乘了 100。多币种场景下，确保创建 Checkout Session 时明确指定 currency
• 支付成功但数据库未更新 — 不要依赖前端回调来确认支付状态，必须以 Webhook 事件为准。前端回调仅用于页面跳转，实际的订单确认和权限开通必须在 Webhook 处理中完成