前言¶
接 Stripe 時，文檔面很廣：一次性收款用 Checkout 還是 PaymentIntent、市場平臺要不要上 Connect Accounts v2、訂閱和用量計費走哪套 Billing API、稅務要不要開 automatic_tax，還有密鑰、Webhook、沙箱怎麼配。自己翻多篇文檔容易選錯 API，或在稅務、履約等細節上踩坑。下面介紹 Stripe 官方在 stripe/ai 倉庫裏維護的 stripe-best-practices Skill：把常見集成場景收成一張決策路由表，並附帶必須遵守的規則與分主題參考文件，供編碼助手在規劃、實現、測試或評審集成時按步驟回答。
這是什麼¶
stripe-best-practices 是面向 Agent 的 Stripe 集成指南 Skill，由 Stripe 維護，源碼位於 https://github.com/stripe/ai/tree/main/skills/stripe-best-practices。
它覆蓋開發與測試環境規劃（獨立 sandbox 與共享 test mode 的取捨）、API 選型（Checkout Sessions、PaymentIntents、Setup Intents 等）、Connect 平臺（Accounts v2、controller 屬性）、計費與訂閱、稅務與登記（Stripe Tax、automatic_tax、產品稅碼）、Treasury 金融賬戶、集成形態（Checkout、Payment Element）、從已棄用 API 遷移，以及安全實踐（API 密鑰、Webhook、OAuth 等）。適用時機包括：規劃或修改任意 Stripe 集成、選開發環境、收款、做市場平臺、接訂閱、處理銷售稅/VAT/GST、創建 Connected Account、或審查密鑰與 Webhook 配置。
Skill 要求使用最新 Stripe API 版本；資料中寫明當前爲 2026-09-30.endive，除非用戶另有指定，應始終使用最新 API 版本與 SDK。
核心功能¶
集成路由（按場景選 API）¶
Skill 用表格把「在做什麼」映射到推薦 API，並在回答或寫代碼前要求閱讀對應 reference 文件（如 references/payments.md、references/connect.md 等）：
| 場景 | 推薦 API |
|---|---|
| 一次性支付 | Checkout Sessions |
| 自定義表單 + 嵌入式 UI | Checkout Sessions + Payment Element |
| 保存支付方式供後續使用 | Setup Intents |
| Connect 平臺或市場 | Accounts v2（/v2/core/accounts） |
| 用量計費（新集成） | Metronome |
| 訂閱或週期性計費 | Billing APIs + Checkout Sessions |
| 銷售稅、VAT、GST | Stripe Tax + Registrations API |
| 嵌入式金融賬戶 / 銀行能力 | v2 Financial Accounts |
| 安全（密鑰、Webhook、OAuth 等） | 見 security reference |
當需求跨多個領域時，Skill 指向 Stripe 文檔中的 Integration Options、API Tour、Go Live Checklist 作爲補充入口。
環境與 SDK 默認值¶
- 新集成開發：默認使用獨立的 sandboxes，而不是賬戶共享的 test mode sandbox；本地與 CI 建議分開 sandbox；僅在舊集成依賴共享 test mode，或某功能尚不支持通用 sandbox 時，才用共享 test mode。
- 無 Stripe 賬戶時：可安裝 Stripe CLI 後創建 sandbox 測試賬戶（無需註冊）。安裝與創建命令見下文「典型用法」。
- API 密鑰：默認推薦 restricted API key（RAK）（
rk_前綴），而非 secret key（sk_）。 - SDK 版本：資料列出各語言最新版本（Ruby 20.0.0、Python 16.0.0、Node.js 23.0.0、PHP 22.0.0、Java 34.0.0、Go 87.0.0、.NET 53.0.0），實現時應與官方 SDK 對齊。
Critical rules（集成時硬約束）¶
Skill 明確若干易錯點，助手在給出方案或代碼時應遵守：
- 稅務：在啓用
automatic_tax: { enabled: true }或爲自定義 PaymentIntent 算稅之前，必須先讀 tax reference，並確認用戶已有 active registration；否則 Stripe 不會計算和代收稅款，但業務側可能誤以爲已含稅。 - 支付方式類型：除 Terminal 當面付需在 PaymentIntent 上傳
payment_method_types: ['card_present']外，不要在任何 Stripe API 調用裏包含payment_method_types；應依賴動態支付方式，或通過payment_method_configurations、excluded_payment_method_types配置。若 PaymentIntent/SetupIntent 需要顯式白名單，用allowed_payment_method_types。 - Webhook：不能把 Webhook 當成可選項；訂閱與異步支付方式依賴 Webhook。履約邏輯應放在
checkout.session.completed與checkout.session.async_payment_succeeded（結合payment_status）的處理程序中，而不是成功頁。 - Checkout 追蹤：API 版本
2026-03-25.dahlia及以後，創建 Checkout Session 時應傳integration_identifier，標籤建議帶 8 位隨機字母后綴，便於在 Dashboard 對比不同收銀流程。 - 客戶端實例化：始終實例化
StripeClient並在實例上調用方法；不要使用已棄用的全局/模塊級設鑰方式（如stripe.api_key = …、Stripe.setApiKey等）。
安裝與啓用¶
通過 skills 安裝工具 從 Stripe 官方倉庫添加該 Skill：
npx skills add https://github.com/stripe/ai --skill stripe-best-practices
也可將 Skill 目錄鏈接交給支持 Agent Skills 的編碼助手，讓其按項目約定安裝：https://github.com/stripe/ai/tree/main/skills/stripe-best-practices。
資料未區分 Cursor、Codex CLI、Claude Code 的安裝差異時，以上述 npx skills add 與 GitHub 路徑爲準。
典型用法¶
1. 用 CLI 快速拿到 sandbox 與測試密鑰¶
無賬戶時，先全局安裝 CLI，再創建 sandbox（Skill 說明 sandbox 即 Stripe 測試環境）：
npm i -g @stripe/cli
stripe sandbox create
若通過 stripe sandbox create 創建環境，Skill 要求不要在該流程下使用 MCP；若之後要用 MCP，需先執行 stripe sandbox claim。檢查 CLI 登錄狀態用：
stripe whoami --format json
不要用 stripe config --list 做鑑權檢查。
2. 向助手描述業務，走集成路由¶
例如：「我們要做 SaaS 月付訂閱，收銀頁希望少維護」——Skill 會導向 Billing APIs + Checkout Sessions，並提示先讀 billing 與 payments 相關 reference，再寫 checkout.sessions.create 等代碼。
又如：「平臺撮合買賣雙方分賬」——路由到 Accounts v2 與 Connect reference，而不是沿用舊版 Connect 賬戶模型。
3. 上線前對照清單¶
Skill 在邊界不清時指向 Go Live Checklist，適合在評審現有集成或準備生產切換時，讓助手按清單項逐條覈對密鑰權限、Webhook、稅務登記等。
適用場景與注意¶
適合誰
- 正在新建或改造 Stripe 收款、訂閱、市場、稅務、Treasury 能力的團隊，希望助手輸出與官方當前推薦一致的 API 選型與代碼形態。
- 需要審計舊集成（棄用全局 SDK 設鑰、
payment_method_types誤用、成功頁履約、未配 Webhook 等）的開發者。
限制與注意
- Skill 是決策與規範層，具體參數與示例仍以 Skill 內
references/*.md及 docs.stripe.com 爲準；回答集成問題前應讀對應 reference。 - 稅務、Connect 責任劃分、OAuth 等話題涉及合規與賬戶配置，Skill 會強調前置條件（如 tax registration），不能替代你在 Stripe Dashboard 與法務流程中的確認。
- 資料僅給出通過
npx skills add的安裝方式；其他 IDE 插件路徑若未在官方頁寫明，不要自行假設。
結尾¶
stripe-best-practices 把 Stripe 多產品線下的集成選擇壓縮成可執行的決策路由和 Critical rules，減少在 Checkout、PaymentIntent、Connect、Billing、Tax 之間誤選 API 的概率，並統一環境、密鑰、Webhook、SDK 用法上的默認值。若你正在用 AI 助手寫或審 Stripe 代碼，可從官方倉庫安裝該 Skill，並在提問時說明業務場景（一次性/訂閱/平臺/稅務等），讓助手先路由再落代碼。
官方地址：https://github.com/stripe/ai/tree/main/skills/stripe-best-practices
