前言¶
接 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
