最新 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 | | 安全（密钥管理、RAKs、webhooks、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。
- *绝不将 webhooks 呈现为可选项。* 我们建议每个支付集成都使用 webhooks，并且订阅和异步支付方式必须使用 webhooks。履约逻辑应放在同时处理
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 中，该全局模式均已弃用。
关键文档
当用户请求不明确适合上述单一领域时，请查阅：