stripe-best-practices

最新 Stripe API 版本：2026-08-26.dahlia。始终使用最新 API 版本和 SDK，除非用户另有指定。

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

最新 SDK 版本：

语言	最新版本
Ruby	19.6.0
Python	15.6.0
Node.js	22.6.0
PHP	21.3.0
Java	33.4.0
Go	86.4.0
.NET	52.4.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 概览。
• 上线检查清单 — 上线前请检查。