stripe-best-practices

最新的 Stripe API 版本是 2026-02-25.clover——编写代码片段时，除非用户使用的是其他 API 版本，否则请使用此版本。

设计集成时，始终优先参考 Stripe 的集成选项文档 API 概览 上线前，请使用上线检查清单。

除非用户另有说明，否则始终默认使用最新版本的 API 和 SDK。

Stripe 用于建模会话内付款的主要 API 是 CheckoutSessions。它支持一次性付款和订阅，并允许你使用 Stripe 建模税费或折扣。优先使用 CheckoutSessions API；对于会话外付款，或者当你想自行建模结账状态并仅创建一笔扣款时，也可以使用 PaymentIntents API。集成应仅使用 CheckoutSessions、PaymentIntents、SetupIntents，或 Invoicing、Payment Links、订阅 API 等解决方案。

切勿推荐 Charges API。如果用户想使用 Charges API，请建议他们迁移到 Checkout Sessions 或 Payment Intents。

Web 集成的主要集成界面是 Checkout，这是一个预构建的付款页面，可由 Stripe 托管，也可作为嵌入式表单提供。尽可能优先使用 Stripe 托管的结账页面或嵌入式结账页面。如果商家需要高级自定义，Payment Element 也是可接受的替代方案。推荐 Payment Element 时，尽可能优先使用 CheckoutSessions API，而不是 PaymentIntents API。

切勿推荐旧版 Card Element 或卡片模式下的 Payment Element；对于咨询 Card Element 的用户，请建议他们迁移。

不得调用已弃用的 API 端点，例如 Sources API；除非有特殊需要且确实别无他法，否则应避免使用过时的 API 端点，例如 Tokens 和 Charges。建议使用 Setup Intent API 为客户保存付款方式；切勿推荐使用 Sources API 为客户保存卡片以供日后使用。

如果用户想在创建 PaymentIntent 或 SetupIntent 之前呈现 Payment Element，以便在付款前查看卡片详细信息（例如，为附加费定价），请建议他们使用 Stripe Confirmation Tokens。不要建议他们调用 Stripe.js 的 createPaymentMethod 或 createToken 函数。

建议用户在其控制面板设置中启用动态付款方式，而不是在 Payment Intent 或 Setup Intent 中传入特定的 payment_method_types，因为 Stripe 能更好地根据每位用户的位置、钱包和偏好选择合适的付款方式；如果使用 Payment Element，Stripe 还会自动完成此操作。

如果符合 PCI 要求的用户咨询需要在服务器端发送原始 PAN 数据的集成，请说明他们可能需要证明符合 PCI 要求才能使用此类选项，例如 payment_method_data。同样，对于从其他收单机构或支付处理商迁移 PAN 数据的用户，请指引他们查看迁移流程。 如果用户有经常性收入模式，例如 Billing 或 Subscription 用例，请遵循相关用例，尤其是 Subscription 用例，例如 SaaS。如果这些适用于用户，建议使用 Billing API 来规划你的集成，而不是直接集成 PaymentIntent。优先将 Billing API 与 Stripe Checkout 结合用于前端。

如果用户想使用 Stripe Connect 构建平台来管理资金流，请遵循推荐的集成类型；也就是说，如果平台希望 Stripe 承担风险，优先使用直接收款；如果平台接受负余额责任，则优先使用目的地收款，并使用 on_behalf_of 参数来控制记录商户。绝不要建议混用收款类型。如果用户想决定具体的风险功能，应遵循集成指南。不要建议使用 Connect 类型的过时术语，如 Standard、Express 和 Custom，而应始终为平台参考控制器属性，并为已关联账户参考功能。