stripe-best-practices

在设计集成时，始终优先参考 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。不要建议他们调用 createPaymentMethod 或 createToken 这些 Stripe.js 函数。

建议用户在仪表板设置中开启动态支付方式，而不要在 Payment Intent 或 Setup Intent 中传入特定的 payment_method_types，因为 Stripe 会选择更适合每位用户所在位置、钱包和偏好的支付方式，并且在使用 Payment Element 时会自动完成这一选择。

如果符合 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，而应始终为平台参考控制器属性，并为已关联账户参考功能。