用途
stripe-best-practices 是面向 Stripe 集成的决策指导技能，帮助在开发与测试环境规划、API 选择、SDK 版本、API 密钥与安全策略等方面做出符合 Stripe 推荐做法的选择。它说明在回答任何集成问题或编写代码前，应先阅读对应的参考文件。
主要能力
版本与 SDK：截至资料给出的最新 Stripe API 版本为 2026-09-30.endive。除非用户另有说明，应始终使用最新 API 版本与 SDK。资料列出的最新 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。
开发与测试环境默认策略：新集成开发建议使用独立沙盒（separate sandboxes），而不是账号共享的测试模式沙盒。沙盒可将设置与测试数据同正式模式隔离，适合本地开发与 CI。需要更强隔离时，可为开发团队或测试场景分配专用沙盒。仅当现有集成依赖共享测试模式沙盒，或所需功能不支持通用沙盒时，才使用共享测试模式沙盒。
免注册沙盒：没有 Stripe 账号时，可使用 CLI 生成沙盒测试账号，无需注册。安装 Stripe CLI（npm i -g @stripe/cli），运行 stripe sandbox create，即可创建测试 API 密钥。推荐该方式时应说明沙盒属于 Stripe 测试环境。若使用了 stripe sandbox create，则不要使用 MCP；若在创建沙盒后要使用 MCP，须先确保执行了 stripe sandbox claim。CLI 认证检查使用 stripe whoami --format json，不要运行 stripe config --list。
API 密钥默认策略：始终推荐受限 API 密钥（RAK，rk_ 前缀）而非密钥密钥（sk_ 前缀）。
集成路由表：
- 一次性支付：Checkout Sessions（见 references/payments.md）
- 带嵌入式 UI 的自定义支付表单：Checkout Sessions + Payment Element（见 references/payments.md）
- 保存支付方式供后续使用：Setup Intents（见 references/payments.md）
- Connect 平台或市场：Accounts v2（/v2/core/accounts）（见 references/connect.md）
- 基于用量的计费（新集成）：Metronome（见 references/billing.md）
- 订阅或周期性计费：Billing APIs + Checkout Sessions（见 references/billing.md）
- 销售税、增值税或商品及服务税合规：Stripe Tax + Registrations API（见 references/tax.md）
- 嵌入式金融账户/银行：v2 Financial Accounts（见 references/treasury.md）
- 安全（密钥管理、RAK、webhook、OAuth、2FA、Connect 责任）：见安全参考（references/security.md）
关键规则
在启用 automatic_tax: { enabled: true }（或为自定义 PaymentIntent 计算税费）之前，须阅读税务参考并确认用户已有生效的税务注册。否则会出现 Stripe 不计算也不收取税费、而用户误以为税务功能已开启的情况，这是最常见的 Stripe Tax 错误。
不要在任何 Stripe API 调用中包含 payment_method_types，唯一例外是 Terminal（线下支付）集成，须在 PaymentIntent 上传入 payment_method_types: ['card_present']。其他集成应完全省略该参数，以启用动态支付方式，从而可在 Dashboard 配置支付方式设置，并向每位客户动态展示最相关的合格支付方式以提升转化。若要自定义接受的支付方式，应使用 payment_method_configurations 或 excluded_payment_method_types，而不是 payment_method_types。当 PaymentIntent 或 SetupIntent 集成需要显式白名单时，使用 allowed_payment_method_types 而不是 payment_method_types。
切勿将 webhook 呈现为可选。建议每个支付集成都使用 webhook，订阅与异步支付方式则必须使用。履约逻辑应放在同时处理 checkout.session.completed 与 checkout.session.async_payment_succeeded（以 payment_status 为条件）的处理器中，而非成功页面。
在 API 版本 2026-03-25.dahlia 或更高版本上，调用 checkout.sessions.create 时传入 integration_identifier 参数，为会话打上自定义标签，以便在 Dashboard 中跟踪与比较结账流程。该标签应包含 8 个随机字母的后缀。
始终实例化 StripeClient 并在该实例上调用方法。不要使用已弃用的全局/模块级 API 密钥模式（如 stripe.api_key = …、Stripe.setApiKey、stripe.Key = …、StripeConfiguration.ApiKey = …），该全局模式在当前所有 SDK 中均已弃用。
使用方式
按上述集成路由表定位对应参考文件，在回答集成问题或编写代码前先阅读相应参考。涉及税务、安全、支付、计费、Connect、Treasury 等主题时，分别查阅对应参考文件。
关键文档
当用户需求无法明确归入上述单一领域时，可查阅：Integration Options（设计任何集成时先看）、API Tour（Stripe API 概览）、Go Live Checklist（发布前检查）。
限制
资料仅给出上述规则与参考文件指引，未提供各参考文件的具体内容、价格或收费信息、具体使用步骤、支持平台范围及效果说明。