stripe-best-practices

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

最新 SDK 版本：

语言	最新版本
Ruby	19.4.0
Python	15.4.0
Node.js	22.4.0
PHP	21.1.0
Java	33.2.0
Go	86.2.0
.NET	52.2.0

如果没有 Stripe 账户，可以调用 CLI 命令生成可用的 API 密钥，无需注册。可以安装 Stripe CLI（npm i -g @stripe/cli），然后运行命令 stripe sandbox create 开始使用。

如果使用了 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。

• 对于 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 功能概览。
• 上线检查清单 — 上线前请查阅。