stripe-patterns

Stripe Integration Patterns 是一套面向 FastAPI 后端与 Next.js 前端的 Stripe 集成模板，提供 Checkout Sessions、Payment Intents 和 Subscription billing 的可复用代码。

用途 适用于在应用中实现 Stripe 支付处理、构建一次性或周期性支付的结账流程、集成订阅计费系统、设置支付事件的 webhook 处理器、使用 Stripe Elements 创建安全支付表单，以及校验 Stripe API 配置。

主要能力 提供三种集成模式：

1. Checkout Sessions（重定向流程）：适合快速集成、托管支付页面、最少前端代码。流程为后端创建带 line items 和 success URL 的 Checkout Session，将客户重定向到 Stripe 托管结账页，通过 checkout.session.completed webhook 完成履约。使用 scripts/setup-stripe-checkout.sh 和 templates/checkout_session.py。
2. Payment Intents（自定义 UI）：适合自定义支付表单、直接收集卡信息、高级 UX 控制。流程为结账开始时后端创建 PaymentIntent，将 client secret 传给前端，用 Stripe Elements 收集支付详情，客户端确认支付，通过 webhook 监控支付成功或失败。使用 scripts/setup-payment-intents.sh 和 templates/payment_intent.py。
3. Subscriptions（周期性计费）：适合经常性收入、订阅服务、会员访问。流程为创建或获取 Customer 对象，将支付方式附加到 customer，创建带定价和计费周期的 Subscription，通过 webhook 处理订阅生命周期事件。使用 scripts/setup-subscriptions.sh 和 templates/subscription.py。

可用脚本

• setup-stripe-checkout.sh：创建完整的 Checkout Session 实现，含 FastAPI 端点、webhook 处理器和成功/取消页面。
• setup-payment-intents.sh：设置 Payment Intent 工作流，含 client secret 处理、Stripe Elements 集成和支付确认。
• setup-subscriptions.sh：实现订阅计费，含客户管理、订阅创建和生命周期 webhook 处理器。
• validate-stripe-config.sh：校验 Stripe 配置，包括 API 密钥、webhook 密钥、环境设置和 .gitignore 保护。

可用模板 后端模板（Python/FastAPI）：

• checkout_session.py：完整 Checkout Session 端点，创建带 line items 的 session，处理成功/取消重定向，返回用于重定向的 session ID。
• payment_intent.py：Payment Intent 工作流，创建带金额/币种的 PaymentIntent，返回给前端的 client secret，处理支付确认。
• subscription.py：订阅管理，客户创建与获取，支付方式附加，带定价的订阅创建。 前端模板（TypeScript/Next.js）：
• stripe_elements.tsx：Stripe Elements 组件，带验证的卡输入，Payment Intent 确认，错误处理和状态更新。
• checkout_page.tsx：完整结账页面，产品展示与定价，Checkout Session 重定向流程，成功/取消页面处理。

可用示例

• fastapi-checkout-example.py：完整可运行示例，含 FastAPI 应用设置、Checkout Session 创建端点、履约 webhook 处理器、环境配置和错误处理。
• nextjs-payment-form-example.tsx：完整支付表单实现，含 Stripe Elements 集成、Payment Intent 确认、加载状态和错误显示、成功/失败处理。
• subscription-flow-example.py：端到端订阅工作流，含客户创建、支付方式收集、订阅创建、webhook 事件处理和订阅生命周期管理。

使用方式

1. 获取 Stripe 密钥：测试模式访问 https://dashboard.stripe.com/test/apikeys 复制 Publishable key 和 Secret key，使用测试卡 4242 4242 4242 4242；生产模式需完成账户验证后访问 https://dashboard.stripe.com/apikeys 复制生产密钥，切勿将生产密钥提交到 git。
2. 配置环境：创建 .env 文件（以 .env.example 为模板），设置 STRIPE_SECRET_KEY、STRIPE_PUBLISHABLE_KEY、STRIPE_WEBHOOK_SECRET，并将 .env、.env.local、.env.development、.env.production 加入 .gitignore，保留 !.env.example。
3. 安装依赖：后端执行 pip install stripe fastapi uvicorn python-dotenv；前端执行 npm install @stripe/stripe-js @stripe/react-stripe-js。
4. 设置 webhook：本地开发安装 Stripe CLI（https://stripe.com/docs/stripe-cli），运行 stripe login，转发事件 stripe listen --forward-to localhost:8000/webhook，将 webhook 签名密钥复制到 .env；生产环境在 Stripe Dashboard 添加端点，选择监听事件，复制 webhook 签名密钥。

安全要求 所有模板遵循严格安全规则：所有 API 密钥使用占位符 your_stripe_key_here；代码仅从环境变量读取；提供带占位符的 .env.example 模板；.gitignore 保护密钥文件；文档说明如何获取 Stripe 密钥；绝不在任何文件中硬编码真实 Stripe API 密钥。

最佳实践 安全方面：始终使用环境变量存储 API 密钥，校验 webhook 签名以防篡改，生产环境所有端点使用 HTTPS，绝不记录敏感支付信息，实现不暴露密钥的错误处理。 支付流程方面：在金额已知时尽早创建 PaymentIntent，存储 PaymentIntent ID 以便页面刷新时检索，使用幂等键安全重试，处理所有可能的支付状态，在 UI 中实现正确的加载状态。 订阅方面：使用 default_incomplete 支付行为，创建订阅前先收集支付方式，正确处理试用期，通过 webhook 监控订阅状态变化，实现正确的取消和升级流程。 测试方面：使用 Stripe 测试卡（https://stripe.com/docs/testing），用 Stripe CLI 测试 webhook 事件，验证拒付卡的错误处理，测试 3D Secure 认证流程，验证成功和失败路径。

常见用例 一次性支付：为简化使用 Checkout Sessions，为自定义 UI 使用 Payment Intents。周期性计费：使用 Subscriptions 并自动生成发票。免费试用：创建订阅时使用 trial_period_days 参数。按用量计费：使用带 metered billing 和用量报告的 Subscriptions。多种支付方式：将支付方式存储在 Customer 对象上并设置默认。

故障排查 支付静默失败：检查 webhook 端点是否可访问，验证 webhook 签名校验，查看 Stripe Dashboard 事件日志。Checkout Session 过期：session 在 24 小时后过期，需创建新 session 重试。订阅状态卡住：检查 Dashboard 中的失败支付，验证支付方式有效，查看订阅支付设置。CORS 错误：在 FastAPI 中配置 CORS 中间件，生产环境允许 Stripe.js 来源。

参考链接 Stripe Checkout：https://docs.stripe.com/payments/checkout Payment Intents：https://docs.stripe.com/payments/payment-intents Subscriptions：https://docs.stripe.com/billing/subscriptions Webhooks：https://docs.stripe.com/webhooks Testing：https://docs.stripe.com/testing