stripe

用途

Stripe 知识库是一份统一的 Stripe 集成参考，供同插件的 stripe-integrator 与 revenue-optimizer 智能体加载，也可被直接使用。触发条件为处理 Stripe API 相关工作时。

内容分为两部分：references/ 存放按主题划分的模式与参考，scripts/ 存放可直接运行的辅助脚本。

主要能力

参考文档（references/）

加载规则如下：

任何 Stripe API 工作 → 先看 references/api-cheatsheet.md 与 references/stripe.md
TypeScript / Next.js 集成（Route Handlers、Server Actions）→ references/typescript-nextjs.md
嵌入式 Checkout（用 React 挂载而非跳转）→ references/embedded-checkout.md
生产环境 Webhook（签名、幂等、事件目录）→ references/webhooks-production.md
按量计费 / 计量定价 → references/billing-meters.md（旧版 usage_type=metered 已在 2025-03-31.basil 中移除）
基于 Stripe 产品的功能门控 → references/entitlements.md
LLM 智能体调用 Stripe（OpenAI Agents SDK / Vercel AI / LangChain / CrewAI / MCP）→ references/stripe-agent-toolkit.md
在测试中模拟订阅生命周期 → references/test-clocks.md
PCI DSS 4.0 / 4.0.1 合规（SAQ-A、SAQ-A-EP）→ references/pci-dss-4-checklist.md
订阅生命周期 → references/subscription-patterns.md、references/usage-revenue-modeling.md
Checkout 转化优化 → references/checkout-optimization.md
定价策略与分层设计 → references/pricing-patterns.md
Firebase + Stripe 集成 → references/firebase-integration.md
Stripe 惯用模式（可复用代码）→ references/stripe-patterns.md
成本分析 / 单位经济模型 → references/cost-analysis.md

参考文档风格说明：较新的文档（billing-meters、entitlements、webhooks-production、typescript-nextjs、embedded-checkout、stripe-agent-toolkit、test-clocks、pci-dss-4-checklist）有意链接到 Stripe 官方文档以获取权威代码示例，而不是在本地镜像这些内容。本地内容仅限于不明显的关键陷阱与决策依据。

脚本（scripts/）

可直接运行的 Python 辅助脚本（需按项目适配，要求 STRIPE_SECRET_KEY 环境变量）：

scripts/setup_products.py -- 为新项目初始化 Products 与 Prices
scripts/stripe_utils.py -- 供其他脚本使用的共享工具函数
scripts/sync_subscriptions.py -- 对账本地数据库与 Stripe 订阅状态
scripts/webhook_handler.py -- 带签名校验与幂等的 Webhook 接收模板
scripts/webhook_audit.py -- 报告已配置 Webhook 端点与必备事件目录之间的缺口
scripts/simulate_subscription.py -- 用测试时钟让订阅走完试用结束、续费、支付失败与恢复的流程

所有脚本位于 ${CLAUDE_PLUGIN_ROOT}/skills/stripe/scripts/<name>.py，智能体应以此路径引用。

使用方式

API 版本说明

Stripe 当前版本（2026 年 5 月）为 2026-05-27.dahlia。版本遵循 YYYY-MM-DD.<release> 命名，release 名称（acacia、basil、dahlia……）标志重大版本边界。同一 release 名称内的月度小版本向后兼容。

建议在所有服务端代码中固定显式版本：

import stripe
stripe.api_version = "2026-05-27.dahlia"

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-05-27.dahlia',
});

现代 Node 与 Python SDK 会在每个 SDK 版本中内置默认 API 版本，因此除非手动覆盖，SDK 本身会固定请求版本。即便如此，仍建议在构造函数中显式固定——这一行记录了你的集成是针对哪个版本编写的。

需要了解的破坏性变更：

2025-03-31.basil 移除了旧版用量记录 API（SubscriptionItem.create_usage_record 与裸的 usage_type=metered 价格）。所有计量价格现在都必须由 Meter 支撑。详见 billing-meters.md。
subscription.current_period_end 已迁移到 subscription.items.data[0].current_period_end。若代码读取顶层字段，在任何现代版本上都会出错。
Dashboard → Workbench 显示账户的默认版本。账户默认版本滞后于重大发布；切勿依赖默认值——请显式固定。

Webhook 可靠性清单

对每个事件用 stripe.Webhook.construct_event 校验签名
使用原始请求体，而非重新序列化的 JSON
幂等：按 event.id 去重（Stripe 在 3 天窗口内重试）
始终在 10 秒内返回 2xx；耗时工作放入队列延迟处理
开发期间通过 stripe events resend 重放历史事件
测试签名失败场景——攻击者会伪造 Webhook

完整说明（按用例划分的事件目录、多环境策略、审计清单）见 references/webhooks-production.md，可运行实现见 scripts/webhook_handler.py。

适用场景

适用于 Stripe API 集成相关的开发与审计工作，包括：核心 API 调用、TypeScript/Next.js 集成、嵌入式 Checkout、生产 Webhook、按量计费与计量、Entitlements 功能门控、LLM 智能体接入 Stripe、测试时钟模拟订阅、PCI DSS 合规、订阅生命周期管理、Checkout 转化优化、定价分层设计、Firebase 集成、成本与单位经济分析。

限制与注意事项

常见陷阱

使用顶层的 subscription.current_period_end——在较新 API 版本中已迁移到 subscription.items.data[0].current_period_end；请对照你固定的版本核实
缓存 customer.default_source——已弃用，改用 invoice_settings.default_payment_method
把 price.id 当作产品标识——price.id 在任何价格更新时都会变化；稳定引用应使用 product.id
在 Payment Intent 上忘记 automatic_payment_methods: { enabled: true }——客户会得到一份默认支付方式列表，通常不含钱包与 BNPL
仍在调用 SubscriptionItem.create_usage_record——已在 API 2025-03-31.basil 中移除。请迁移到 stripe.billing.MeterEvent.create（见 references/billing-meters.md）
在计费托管于 Stripe 时自行维护 plan.features 映射——应使用 Stripe Entitlements，并通过 entitlements.active_entitlement_summary.updated Webhook 缓存（见 references/entitlements.md）

技能介绍

用途