用途:该技能定位为 Stripe 高级支付解决方案架构助手,面向需要构建安全、合规、可扩展支付系统的开发场景,尤其结合 Next.js 16 与 React 19。
主要能力:覆盖结账流程(Checkout Sessions 托管或嵌入式)、支付元素定制、用量制与混合计费(Billing Meters)、Stripe Tax 全球税务与增值税/GST 自动处理,以及 Webhook 验签、幂等与履约逻辑。
必要用法与规范:
- 集成选择优先 Checkout Sessions,覆盖约 90% 场景;仅当需要高度 UI 定制时才用 Payment Element。
- 密钥与敏感逻辑必须放在 Server Actions 或 Route Handlers,禁止信任客户端传入的价格或数量。
- 会话创建需在服务端完成,示例使用 Server Actions:在 app/actions/stripe.ts 中标记 "use server",用 loadStripe 作为单例初始化,并按代码示例写入 apiVersion、line_items、mode、success_url、cancel_url、automatic_tax 与 idempotencyKey。
- 所有对 Stripe 的变更请求须携带 idempotency_key,防止重复提交。
- 开启 automatic_tax 处理全球税务关联与 VAT/GST。
- 用量计费通过 billing.meterEvents.create 异步上报事件,避免阻塞用户流程。
- Webhook 处理须做签名验证与幂等检查,记录事件后立即返回 200,避免 Stripe 重试导致长时间处理。
- 本地测试可用 Stripe CLI,集成审计可尝试 stripe-check(如可用);附带 scripts/verify-webhooks.ts 本地 Webhook 模拟工具与 scripts/sync-prices.py 价格同步脚本。
禁止事项:不使用旧版 Charges API,改用 PaymentIntents 或 Checkout Sessions;不使用单行 Card Element,改用 Payment Element 支持多支付方式;不在服务器存储原始卡数据;不依赖 success_url 完成业务逻辑,履约只通过 Webhook;不指定具体 payment_method_types,改在后台启用动态支付方式。
适用场景:SaaS 订阅、用量制计费、混合计费、跨境税务合规、Next.js 16 支付集成。
限制:资料未提供具体收费标准、价格信息与平台兼容性细节;工具脚本的实际可用性及 stripe-check 存在性需自行确认。学习资源包括 Stripe 官方文档、API 参考与 GitHub 示例。