adding-stripe：让 AI Agent 按标准流程接入 Stripe 支付

大模型Skills adding-stripe Stripe支付 Agent Skill Webhook Cursor 2026-08-15 69 阅读

前言

SaaS 或内容站点一旦要收费，通常就要同时处理结账页、一次性付款或订阅、支付成功后的权限开通，以及用户自己改套餐、取消订阅。Stripe 是海外项目里最常见的方案之一，但官方文档覆盖 Checkout Session、Webhook 验签、Billing Portal、价格目录等多个环节。漏掉签名校验、把密钥写到前端、或在本地测不到 Webhook，都是集成时的高频问题。

adding-stripe 是社区 Skill 清单 awesome-cursor-skills 里的一条工作流指令，把「给 Web 应用加 Stripe」拆成可复用的 SKILL.md。当你在 Cursor、Claude Code、Codex CLI 等支持 Agent Skills 的工具里说「加支付」「做订阅」「接 Stripe」时，Agent 会按这份 7 步清单执行，而不是从零拼文档。

这是什么

adding-stripe 是一份 Agent Skill 配置文件，维护在 spencerpauly/awesome-cursor-skills/resources/adding-stripe，由社区策展收录，并非 Stripe 官方出品。仓库 README 把它归在 Authentication & Payments 分类，一句话说明是：Integrate Stripe checkout, subscriptions, webhooks, and customer portal。

SKILL.md 的 YAML 描述是：Integrate Stripe payments into a web application, including checkout sessions, webhooks, and customer portal。触发条件写得很明确——用户提到 payments、billing、subscriptions 或 Stripe integration 时使用。

它属于「把官方常见集成路径翻译成 Agent 可执行清单」的类型：依赖 stripe 与 @stripe/stripe-js，用 Checkout Session 做托管结账，用 Webhook 同步订阅状态，可选接入 Customer Portal。示例路径（lib/stripe.ts、NEXT_PUBLIC_*、localhost:3000）明显面向 Next.js 一类 Node Web 应用，而不是通用的 Stripe Connect 或自定义 Payment Element 全套方案。

核心功能与亮点

根据 Skill 原文，并与 Stripe Checkout Session API、Webhook 文档、Customer Portal 集成指南 交叉核对，这份清单覆盖下面几件事。

  1. 安装服务端与浏览器 SDK
    npm install stripe @stripe/stripe-js。stripe 是官方 Node 库（stripe-node），负责密钥、Checkout、Webhook、Portal；@stripe/stripe-js 是官方 Stripe.js 加载工具，客户端用 loadStripe 拿可发布密钥。

  2. 环境变量
    Skill 要求配置 STRIPE_SECRET_KEY、NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY、STRIPE_WEBHOOK_SECRET，示例值分别是 sk_test_...、pk_test_...、whsec_...。前缀 NEXT_PUBLIC_ 表示可发布密钥给 Next.js 客户端用；密钥（sk_、whsec_）必须只放服务端。

  3. 集中创建 Stripe 客户端
    在 lib/stripe.ts 用 STRIPE_SECRET_KEY 实例化：

   import Stripe from "stripe";

   export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
     apiVersion: "2024-12-18.acacia",
   });

2024-12-18.acacia 是 Stripe 真实存在的 API 版本（Acacia）。需要注意：截至 2026 年 8 月，stripe-node 较新版本默认钉的是更新的版本（例如 2026-07-29.dahlia）。Skill 写死了 Acacia，Agent 可能原样复制；升级 SDK 时要以 Stripe 升级说明 和当前 stripe 包为准，不要混用未核对过的类型定义。

  1. 创建 Checkout Session
    Skill 给出的核心调用是 stripe.checkout.sessions.create：mode 可为 "subscription" 或一次性 "payment"；line_items 使用 Price ID；success_url 带官方占位符 {CHECKOUT_SESSION_ID}（Stripe 会替换成真实 Session ID）；失败回 cancel_url。创建成功后重定向到 session.url，也就是 Stripe 托管的结账页。

  2. Webhook 处理订阅生命周期
    在 POST /api/webhooks/stripe 用 stripe.webhooks.constructEvent 验签，并处理：checkout.session.completed、customer.subscription.updated、customer.subscription.deleted、invoice.payment_failed，再把订阅状态写回自己的数据库。这与 Stripe 对订阅/门户场景的事件建议一致。

  3. 可选的客户门户
    增加一个接口，调用 stripe.billingPortal.sessions.create，把用户重定向到 Stripe 的账单门户，让用户自己管理订阅。Stripe 文档确认：需要先在 Dashboard 配置门户功能，创建 Session 时通常要传 customer 和 return_url。

  4. 定价页 UI
    做一套套餐卡片，点击后调用上面的 Checkout API。Skill 还建议用 stripe.prices.list 动态拉价格，而不是把 Price ID 写死在前端。

Notes 里还有四条实践，均可在 Stripe 文档中找到对应依据：永远校验 Webhook 签名；本地用 Stripe CLI 转发事件；在用户表里保存 Stripe Customer ID，避免重复创建客户；价格走 API 列表而不是硬编码。

安装与启用

Skill 是标准 SKILL.md 格式，可在 Cursor、Claude Code、Codex CLI 等兼容 Agent Skills 的工具里使用。下面方式来自仓库 README、skills.sh 与 Cursor Skills 文档，任选其一即可。

方式一：手动复制（Cursor 通用）

awesome-cursor-skills README 说明：把 SKILL.md 放到 .cursor/skills/（项目级或用户级），Agent 会自动发现。

mkdir -p .cursor/skills/adding-stripe
curl -o .cursor/skills/adding-stripe/SKILL.md \
  https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/adding-stripe/SKILL.md

按 Cursor 文档，项目级还会扫描 .agents/skills/；用户级对应 ~/.cursor/skills/、~/.agents/skills/。为兼容其他工具，Cursor 也会加载 .claude/skills/、.codex/skills/ 以及对应的家目录。目录结构类似：

.cursor/skills/adding-stripe/SKILL.md

方式二：Skills CLI（多 Agent 一键安装）

Vercel Skills CLI 与 skills.sh 给出的安装命令如下：

# 列出仓库内可用 Skill
npx skills add spencerpauly/awesome-cursor-skills --list

# 只安装 adding-stripe（Cursor）
npx skills add spencerpauly/awesome-cursor-skills --skill adding-stripe -a cursor

# 安装到 Claude Code
npx skills add spencerpauly/awesome-cursor-skills --skill adding-stripe -a claude-code

# 安装到 Codex CLI
npx skills add spencerpauly/awesome-cursor-skills --skill adding-stripe -a codex

skills.sh 页面上的等价写法是：

npx skills add https://github.com/spencerpauly/awesome-cursor-skills --skill adding-stripe

安装位置以 CLI 检测为准：Cursor 常见为项目 .cursor/skills/ 或 .agents/skills/；Claude Code 为 .claude/skills/；Codex 为 ~/.codex/skills/ 或项目 .codex/skills/。

安装后一般不用再开「开关」。Cursor 里可在 Agent 对话输入 /，搜索 adding-stripe 手动调用；描述匹配（加支付、订阅、Stripe）时，Agent 也可能根据 frontmatter 的 description 自动选用。

典型用法示例

触发方式

Skill 声明在用户要求加支付、账单、订阅或 Stripe 集成时使用。可以直接说：

  • 「给这个 Next.js 项目接上 Stripe 订阅」
  • 「加一个定价页，点按钮跳到 Stripe Checkout」
  • 「写 Stripe Webhook，同步订阅状态到数据库」
  • 「让用户能自己管理订阅（Customer Portal）」

也可以显式输入 /adding-stripe。

Agent 将执行的集成流程

以下步骤摘自 Skill 原文，并对照 Stripe 官方接口，便于核对 Agent 产出。

1. 安装依赖

npm install stripe @stripe/stripe-js

2. 写入环境变量

在 Stripe Dashboard 的测试模式取出密钥，以及用 Stripe CLI listen 时打印的 webhook signing secret：

STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

3. 创建服务端客户端 lib/stripe.ts

见上一节示例。不要把 STRIPE_SECRET_KEY 传到浏览器。

4. 创建 Checkout API

Skill 中的 Session 创建示例如下（mode 按一次性付款或订阅切换）：

const session = await stripe.checkout.sessions.create({
  mode: "subscription", // or "payment" for one-time
  payment_method_types: ["card"],
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${origin}/pricing`,
  customer_email: userEmail,
});
return redirect(session.url!);

priceId 应来自 Dashboard 里已创建的 Product/Price，或 stripe.prices.list。payment_method_types: ["card"] 在 Checkout API 中合法；Stripe 当前也允许省略该字段，改由 Dashboard 管理可用支付方式。若项目需要更多本地支付方式，不要假定 Agent 会自动加上。

5. Webhook：验签后再改库

Skill 要求 POST /api/webhooks/stripe，使用 constructEvent。Stripe 文档强调：验签必须使用未被解析改写的原始请求体。Next.js App Router 里应先 request.text()，不要先 request.json() 再序列化回去，否则签名几乎必然失败。Node 侧的典型调用是：

const event = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET!
);

验签失败返回 4xx，不要继续处理。通过后再按 event.type 更新本地订阅状态。

本地调试用 Stripe CLI（Skill 给出的命令，与官方 CLI 的 --forward-to 一致）：

stripe listen --forward-to localhost:3000/api/webhooks/stripe

CLI 会输出一个 whsec_...，填进 STRIPE_WEBHOOK_SECRET。生产环境要在 Dashboard 登记 HTTPS 端点，并改用线上 signing secret。

6. 客户门户（可选）

服务端创建门户 Session 后重定向。Stripe Node 示例为：

const session = await stripe.billingPortal.sessions.create({
  customer: customerId,
  return_url: "https://example.com/account",
});

这要求你已经把 Stripe Customer ID 存进用户表——也正是 Skill Notes 强调的一点。

7. 定价页

用套餐卡片调用 Checkout 接口。价格列表优先 stripe.prices.list，避免前后端各写一份 Price ID。

适用场景与注意事项

适合谁用

  • 正在用 Next.js（或同类 Node Web 框架）做 SaaS / 会员站，需要一次性付款或订阅。
  • 已在 Cursor / Claude Code / Codex 里用 Agent 写代码，希望「加 Stripe」有一份固定 checklist，少漏 Webhook 验签和 Customer ID。
  • 接受 Stripe 托管 Checkout 与官方 Customer Portal，而不是一开始就自建完整支付表单。

使用限制与注意点

  1. 这是流程说明，不是 Stripe 官方 Skill
    仓库同页还链到过 Cursor Marketplace 里的 Stripe 插件（如 stripe-best-practices、upgrade-stripe）。adding-stripe 只覆盖 Checkout + Webhook + Portal 这条入门路径，不包含 Connect、Payment Intents 自定义支付页、税务、争议等。

  2. 示例绑定 Next.js 习惯
    环境变量名、lib/stripe.ts、/api/webhooks/stripe、localhost:3000 都按 Next.js 常见结构来写。Express、Remix、非 Node 后端需要在提示里写明框架，并核对「原始 body 验签」在该框架里怎么关 JSON 中间件。

  3. API 版本会过时
    Skill 钉死 2024-12-18.acacia。新版 stripe npm 包的类型往往只跟踪最新 API。若 TypeScript 报错或字段对不上，对照当前 SDK 与 API 版本说明，而不是强行忽略类型。

  4. Webhook 必须验签，且要用原始 body
    未校验的 /api/webhooks/stripe 是公开 POST，伪造 checkout.session.completed 就能开通会员。Stripe 明确要求 HMAC 验签；框架若改写了 body，constructEvent 会失败。

  5. 密钥与测试模式
    sk_、whsec_ 只放环境变量，不要提交到 Git，也不要出现在客户端打包结果里。先在测试模式跑通，再用 live key 和线上 Webhook 端点。Dashboard 里要先有 Product 和 Price，否则 line_items.price 会直接报错。

  6. 门户与重复客户
    billingPortal.sessions.create 需要已有 Customer。Skill 要求把 Customer ID 存进用户表，避免每次 Checkout 都新建客户，导致门户、发票和订阅对不上同一个人。

  7. Agent 产出仍要人工过一遍
    Skill 不会替你完成 PCI 范围评估、税务、发票合规或退款策略。生成的路由、权限开通逻辑和幂等处理（Stripe 会重试 Webhook）需要按业务核对。

小结

adding-stripe 把 Stripe 在 Web 应用里最常见的一条商业化路径——安装 SDK、配密钥、Checkout Session、Webhook 验签、可选 Customer Portal、定价页——写成 Agent 可跟随的 7 步清单。它不扩大 Stripe 本身的能力边界，而是降低漏验签、漏存 Customer ID、把密钥暴露到前端这类集成错误的概率。

官方 Skill 地址：https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/adding-stripe

相关文档：

相关文章

Cursor 3 多 Agent 架构：Planner/Worker 分工最高降本 15 倍 2026-07-29 Cursor 多 Agent 蜂群用 1339 美元重建 SQLite：Planner/Worker 分层才是 Agent 经济学 2026-07-30 600 亿美元收购 Cursor：SpaceX/xAI 要重塑 AI 编程工具格局？ 2026-07-31 Cursor 3 多 Agent 架构：Planner/Worker 分层如何将编码成本降低 15 倍 2026-08-01 GitHub 爆火 Ponytail：让 AI Agent 像「最懒的高级工程师」一样写代码 2026-08-02
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜