mcpField
S
stripe-integration

stripe-integration

github.com/oakoss开发2191 次安装12 周前更新
代码仓库

关于 stripe-integration

stripe-integration 是面向开发者的 Stripe 支付集成指南，涵盖 Node.js 服务端和 React Stripe.js 客户端流程。内容涉及一次性付款、订阅、托管结账和 Webhook 验证。

主要功能

  1. 01创建 Payment Intents 和订阅
  2. 02集成托管结账与支付表单
  3. 03管理客户账单门户
  4. 04验证 Webhook 签名
  5. 05处理支付确认与身份验证

适用场景

  1. 01构建一次性付款流程
  2. 02实现定期订阅和账单管理
  3. 03通过 Webhook 触发履约
  4. 04排查支付确认与事件处理问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill stripe-integration

安装后在 Claude Code 中输入/stripe-integration确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
checkout-and-payments.md
stripe-elements.md
subscriptions.md
webhooks.md

详细介绍

Stripe 集成

概览

Stripe 提供完整的支付平台，包含服务端 SDK（Node.js）和客户端库（Stripe.js、React Stripe.js）。Node.js SDK 处理创建 Payment Intent、管理订阅和验证 Webhook 等服务端操作。React Stripe.js 库提供预构建的 UI 组件（PaymentElement、Elements 提供程序），用于安全地收集客户端支付信息。

适用场景： 一次性付款、周期性订阅、按用量计费、Marketplace 付款、托管结账页面、自定义支付表单、由 Webhook 驱动的履约。

不适用场景： 加密货币支付（不支持）、Stripe 不可用的地区、无需处理支付的简单静态商品销售（请使用托管店面）。

快速参考

模式API要点
托管结账stripe.checkout.sessions.create()Stripe 托管页面，支持 payment、subscription、setup 模式
Payment Intentstripe.paymentIntents.create()服务端操作，返回用于客户端确认的 client_secret
确认支付stripe.confirmPayment({ elements, clientSecret })客户端操作，需要 Elements 实例
创建订阅stripe.subscriptions.create()对于 SCA，使用 payment_behavior: 'default_incomplete'
更新订阅stripe.subscriptions.update()明确设置 proration_behavior
取消订阅stripe.subscriptions.cancel()使用 prorate: true 抵扣未使用的时间
客户门户stripe.billingPortal.sessions.create()自助式账单管理，返回短时有效的 URL
验证 Webhookstripe.webhooks.constructEvent()需要原始请求体、签名标头和端点密钥
Elements 提供程序<Elements stripe={stripePromise} options={options}>包装支付组件，传入 clientSecret 或 mode
PaymentElement<PaymentElement />自动呈现所有受支持的支付方式
检索并展开stripe.checkout.sessions.retrieve(id, { expand })展开嵌套对象以减少 API 调用
搜索stripe.paymentIntents.search({ query })使用 Stripe Query Language 进行筛选

常见错误

错误正确做法
验证前将 webhook 请求体解析为 JSON使用 express.raw({ type: 'application/json' }) 将原始请求体传递给 constructEvent
将支付方式类型硬编码使用 automatic_payment_methods，或让 Checkout 根据币种和地区进行选择
在客户端创建 PaymentIntent在服务端创建，仅将 client_secret 传递给客户端
确认前未等待 elements.submit()先调用 elements.submit() 触发验证，然后调用 confirmPayment
在 confirmPayment 中缺少 return_url始终为基于重定向的支付方式提供 return_url
在生产环境中使用测试密钥将密钥存储在环境变量中，并验证 STRIPE_SECRET_KEY 前缀（sk_live_ 与 sk_test_）
未处理 requires_action 状态确认后检查 PaymentIntent 状态，并处理 3D Secure 或其他身份验证
创建 Customer Portal 会话时未配置设置先在 Dashboard 中保存 Portal 设置，否则 API 会返回错误
未展开相关对象使用 expand 参数包含嵌套对象，例如 latest_invoice.payment_intent
忽略 webhook 幂等性使用 event.id 去重；webhook 事件可能会多次送达

委派

  • 支付流程架构：使用 Explore Agent 查找集成模式
  • Webhook 调试：使用 Task Agent 进行端到端事件追踪
  • 代码审查：委派给 code-reviewer Agent，对支付处理程序进行安全审查

参考资料

评论

支持 Markdown