stripe-integration

核心用法

Stripe Integration Skill 是一套面向生产环境的支付处理集成指南，覆盖从基础支付到复杂市场平台的全场景需求。核心用法包括：

1. 支付流程选择

• Hosted Checkout：Stripe托管支付页，PCI合规负担最小，适合快速上线
• Payment Intents：自定义UI，需配合Stripe.js实现，灵活性更高
• Setup Intents：仅保存支付方式，用于订阅和后续扣款

2. 订阅系统构建
通过Product-Price-Subscription三层模型管理周期性计费，支持客户自助门户（Customer Portal）管理订阅。

3. Webhook安全处理
必须实现签名验证（stripe.Webhook.construct_event），关键事件包括checkout.session.completed、、payment_intent.succeeded、、customer.subscription.deleted等。

4. Stripe Connect市场平台
支持Direct Charge（卖家主导）、Destination Charge（平台主导）、Separate Charges & Transfers（最大灵活）三种模式，需特别注意Direct Charge的webhook路由到Connect端点而非平台端点。

5. 生产级关键模式

• 双重确认：Webhook（异步可靠）+ 前端轮询（即时体验），通过条件UPDATE实现幂等
• 100%折扣码检测：通过amount_total === 0 && payment_status === 'paid''识别，而非no_payment_required
• 跨平台浏览器处理：Web端result.type === 'opened''时用户仍在支付页，不可立即验证；Native端'dismiss''/'/'cancel''`后方可验证
• 库存原子性：支付确认后通过数据库事务原子扣减库存，防止超卖

显著优点

1. 生产经验沉淀：包含大量真实踩坑案例（如Direct Charge webhook遗漏、100%折扣码误判、跨平台浏览器行为差异），非官方文档能覆盖
2. 安全设计内建：强制webhook签名验证、幂等性条件UPDATE、PCI合规指引（不处理原始卡号）
3. 完整场景覆盖：从一次性支付、订阅、退款、争议处理到Connect市场平台，形成闭环
4. 代码即文档：16个可运行代码示例，涵盖Python/TypeScript/SQL，直接可用
5. 测试友好：提供测试卡号矩阵（成功/拒绝/3D验证/余额不足），支持完整流程验证

潜在缺点与局限性

1. 无现成SDK封装：纯文档指导，需开发者自行实现业务适配层
2. 技术栈偏向：示例以Python后端+React Native/Web前端为主，其他语言生态（Go、Java、Flutter）需自行翻译
3. Stripe版本锁定未明确：未指定stripe SDK推荐版本，新API变更可能导致示例失效
4. 复杂业务场景需扩展：如分期付款、多币种动态定价、复杂优惠叠加等高级场景仅提及基础模式
5. 监控告警缺失：未涉及支付成功率监控、异常告警、对账自动化等运维层面

适合的目标群体

• SaaS创业者：快速搭建订阅计费系统，避免支付流程踩坑
• 全栈开发者：需要端到端支付实现参考，尤其跨Web/Native场景
• 市场平台架构师：理解Stripe Connect三种收费模式的取舍与webhook架构
• 技术团队Lead：建立团队支付开发规范，统一幂等性、错误处理等工程实践
• 支付系统迁移者：从其他支付渠道（PayPal、Adyen）迁移至Stripe的技术评估

使用风险

1. 配置错误风险：API Key、Webhook Secret配置错误导致支付失败或安全漏洞，需严格区分test/live环境
2. 幂等性实现遗漏：未正确实现条件UPDATE可能导致重复发货、重复扣减库存
3. Webhook端点遗漏：Direct Charge场景下未配置Connect端点将导致支付状态丢失
4. 跨平台行为误判：Web端按Native逻辑立即验证支付，导致用户未完成支付即判定失败
5. PCI合规责任：虽使用Stripe托管页降低负担，但仍需完成SAQ A问卷，自定义UI需更严格合规
6. 依赖项风险：stripe SDK版本升级可能引入Breaking Change，建议锁定版本并监控changelog