Stripe 支付集成
面向游戏 / Web 应用变现的 Stripe 支付集成指南。
核心原则
必须使用
- CheckoutSessions API —— 一次性支付 + 订阅的基础
- 优先使用 Stripe 托管结账或嵌入式结账
- 动态支付方式 —— 在仪表板中启用（禁止硬编码 payment_method_types）
- 使用最新 API 版本 + SDK
绝对禁止
- ❌ Charges API（旧版，应迁移到 PaymentIntents）
- ❌ Card Element / Payment Element card 模式（旧版）
- ❌ Sources API（已弃用）
- ❌ Tokens API（改用 SetupIntents）
- ❌ 硬编码 payment_method_types（应使用动态支付方式）
按场景选择
变现类型 → 卖什么？
- 一次性游戏购买 → CheckoutSessions（one-time）
- 应用内购买 / 道具 → CheckoutSessions + metadata
- 月费订阅 → Billing API + CheckoutSessions
- 捐赠 / 赞助 → Payment Links（最简单）
- 市场平台 → Stripe Connect（destination charges）
基本实现模式
// 服务端（Node.js）
const session = await stripe.checkout.sessions.create({
mode: 'payment', // 或 'subscription'
line_items: [{
price_data: {
currency: 'usd',
product_data: { name: 'Game Premium' },
unit_amount: 999, // $9.99（以分为单位！）
},
quantity: 1,
}],
success_url: 'https://eastsea.monster/thanks?session_id={CHECKOUT_SESSION_ID}',
cancel_url: 'https://eastsea.monster/games/',
});
// 跳转到 session.url
订阅模型（SaaS / 游戏高级版）
- Billing API → 订阅设计指南：docs.stripe.com/billing/subscriptions/designing-integration
- 优先使用 CheckoutSessions + Billing 组合
- 通过 Webhook 感知订阅状态变更
平台（多个游戏开发者）→ Connect
- destination charges —— 由我们承担 liability
- 使用 on_behalf_of 参数控制 merchant of record
- 禁止混用 charge type
安全清单
- 仅在服务端使用密钥（secret key）
- 验证 Webhook 签名
- 禁止在客户端硬编码金额 / 价格（由服务端生成）
- 完成 go-live 清单：docs.stripe.com/get-started/checklist/go-live
- 必须使用 HTTPS
参考文档
- 集成选项：docs.stripe.com/payments/payment-methods/integration-options
- API 导览：docs.stripe.com/payments-api/tour
- Go-live 清单：docs.stripe.com/get-started/checklist/go-live
守则（Guardrails）
- 必须明确区分测试模式与实时模式 —— 执行代码前明确当前密钥是 sk_test_（测试）还是 sk_live_（实时）。实时模式操作时始终在日志中输出 [LIVE] 标签。
- 修改金额 / 货币时需双重确认 —— 修改 unit_amount、currency 值时，需先向 Master 确认修改前后金额再执行。注意以分为单位的混淆（$9.99 → 999）。
- 绝对禁止泄露 Webhook 密钥 —— STRIPE_WEBHOOK_SECRET 的值绝不输出到日志、响应体或客户端代码。仅通过环境变量管理。
- 退款 / 取消操作执行前需 Master 确认 —— stripe.refunds.create()、订阅 cancel() 等涉及资金的操作执行前必须获得 Master 明确批准。禁止在自动化脚本中单独执行这类操作。