stripe-best-practices

最新的 Stripe API 版本：2026-09-30.endive。始终使用最新的 API 版本和 SDK，除非用户另有说明。

开发和测试环境默认设置：开发新集成时，请使用独立的沙盒，而不是账户共享的测试模式沙盒。沙盒可将设置和测试数据与实时模式隔离。请为本地开发和 CI 使用独立的沙盒。在需要更强隔离时，可为开发团队或测试场景专门创建沙盒。仅当现有集成依赖共享测试模式沙盒，或所需功能不支持通用沙盒时，才使用共享测试模式沙盒。

最新 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

如果你没有 Stripe 账户，可以使用 CLI 生成沙盒测试账户，无需注册。安装 Stripe CLI（npm i -g @stripe/cli），并运行命令 stripe sandbox create，即可生成测试 API 密钥。推荐使用此方法时，请说明沙盒是 Stripe 的测试环境。

如果使用了 stripe sandbox create，请勿使用 MCP。

如果在创建沙盒后尝试使用 MCP，请先确保运行了 stripe sandbox claim。使用 stripe whoami --format json 检查 CLI 身份验证；不要运行 stripe config --list。

API 密钥默认设置：始终优先推荐受限 API 密钥（RAK）（前缀为 rk_），而不是密钥（前缀为 sk_）。

集成方案选择

正在构建……	推荐 API	详情
一次性付款	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>
销售税、VAT 或 GST 合规	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；订阅和异步支付方式则必须使用 Webhook。订单履约逻辑应放在 checkout.session.completed 和 checkout.session.async_payment_succeeded 的处理程序中（并以 payment_status 为条件），而不是放在成功页面中。请参阅 <references/payments.md>。

• 在 API 版本 2026-03-25.dahlia 或更高版本中，调用 checkout.sessions.create 时请传入参数 integration_identifier，为会话添加自定义标签，以便在 Dashboard 中追踪和比较结账流程。标签应以 8 个随机字母作为后缀。

• 始终实例化 StripeClient，并调用该实例上的方法。 不要使用已弃用的全局／模块级 API 密钥模式（stripe.api_key = …、Stripe.setApiKey、stripe.Key = …、StripeConfiguration.ApiKey = …）。所有当前 SDK 中的全局模式都已弃用。

关键文档

如果用户的请求不明确属于上述某个领域，请查阅：

• 集成选项 — 设计任何集成时，请从这里开始。
• API 概览 — Stripe API 功能概览。
• 上线检查清单 — 发布前请查阅。