前言¶

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 集成指南交叉覈對，這份清單覆蓋下面幾件事。

安裝服務端與瀏覽器 SDK
npm install stripe @stripe/stripe-js。stripe 是官方 Node 庫（stripe-node），負責密鑰、Checkout、Webhook、Portal；@stripe/stripe-js 是官方 Stripe.js 加載工具，客戶端用 loadStripe 拿可發佈密鑰。
環境變量
Skill 要求配置 STRIPE_SECRET_KEY、NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY、STRIPE_WEBHOOK_SECRET，示例值分別是 sk_test_...、pk_test_...、whsec_...。前綴 NEXT_PUBLIC_ 表示可發佈密鑰給 Next.js 客戶端用；密鑰（sk_、whsec_）必須只放服務端。
集中創建 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 包爲準，不要混用未覈對過的類型定義。

創建 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 託管的結賬頁。
Webhook 處理訂閱生命週期
在 POST /api/webhooks/stripe 用 stripe.webhooks.constructEvent 驗籤，並處理：checkout.session.completed、customer.subscription.updated、customer.subscription.deleted、invoice.payment_failed，再把訂閱狀態寫回自己的數據庫。這與 Stripe 對訂閱/門戶場景的事件建議一致。
可選的客戶門戶
增加一個接口，調用 stripe.billingPortal.sessions.create，把用戶重定向到 Stripe 的賬單門戶，讓用戶自己管理訂閱。Stripe 文檔確認：需要先在 Dashboard 配置門戶功能，創建 Session 時通常要傳 customer 和 return_url。
定價頁 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，而不是一開始就自建完整支付表單。

使用限制與注意點¶

這是流程說明，不是 Stripe 官方 Skill
倉庫同頁還鏈到過 Cursor Marketplace 裏的 Stripe 插件（如 stripe-best-practices、upgrade-stripe）。adding-stripe 只覆蓋 Checkout + Webhook + Portal 這條入門路徑，不包含 Connect、Payment Intents 自定義支付頁、稅務、爭議等。
示例綁定 Next.js 習慣
環境變量名、lib/stripe.ts、/api/webhooks/stripe、localhost:3000 都按 Next.js 常見結構來寫。Express、Remix、非 Node 後端需要在提示裏寫明框架，並覈對「原始 body 驗籤」在該框架裏怎麼關 JSON 中間件。
API 版本會過時
Skill 釘死 2024-12-18.acacia。新版 stripe npm 包的類型往往只跟蹤最新 API。若 TypeScript 報錯或字段對不上，對照當前 SDK 與 API 版本說明，而不是強行忽略類型。
Webhook 必須驗籤，且要用原始 body
未校驗的 /api/webhooks/stripe 是公開 POST，僞造 checkout.session.completed 就能開通會員。Stripe 明確要求 HMAC 驗籤；框架若改寫了 body，constructEvent 會失敗。
密鑰與測試模式
sk_、whsec_ 只放環境變量，不要提交到 Git，也不要出現在客戶端打包結果裏。先在測試模式跑通，再用 live key 和線上 Webhook 端點。Dashboard 裏要先有 Product 和 Price，否則 line_items.price 會直接報錯。
門戶與重複客戶
billingPortal.sessions.create 需要已有 Customer。Skill 要求把 Customer ID 存進用戶表，避免每次 Checkout 都新建客戶，導致門戶、發票和訂閱對不上同一個人。
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

相關文檔：

Stripe Checkout Session：https://docs.stripe.com/api/checkout/sessions/create
Webhook：https://docs.stripe.com/webhooks
Customer Portal：https://docs.stripe.com/customer-management/integrate-customer-portal
Cursor Skills：https://cursor.com/docs/skills

adding-stripe：讓 AI Agent 按標準流程接入 Stripe 支付

前言¶

這是什麼¶

核心功能與亮點¶

安裝與啓用¶

方式一：手動複製（Cursor 通用）¶

方式二：Skills CLI（多 Agent 一鍵安裝）¶

典型用法示例¶

觸發方式¶

Agent 將執行的集成流程¶

適用場景與注意事項¶

適合誰用¶

使用限制與注意點¶

小結¶

精选优惠券

adding-stripe：讓 AI Agent 按標準流程接入 Stripe 支付

前言¶

這是什麼¶

核心功能與亮點¶

安裝與啓用¶

方式一：手動複製（Cursor 通用）¶

方式二：Skills CLI（多 Agent 一鍵安裝）¶

典型用法示例¶

觸發方式¶

Agent 將執行的集成流程¶

適用場景與注意事項¶

適合誰用¶

使用限制與注意點¶

小結¶

精选优惠券

相關文章