SuperAPI AI 工具集

stripe-best-practices

编程与开发

查看项目

更新于 11-12 06:46

技能介绍

本技能为构建 Stripe 集成提供实践规范建议,适用于支付处理、结账流程、订阅、Webhook、Connect 平台等场景。

用途与总体原则 设计集成时应优先参考 Stripe 官方的 Integration Options 文档、API Tour,并在上线前使用 Go Live Checklist。除非用户另行说明,默认使用最新版本的 API 与 SDK。

支付建模 Stripe 用于建模会话内支付的主要 API 是 CheckoutSessions,支持一次性支付与订阅,并可在 Stripe 侧建模税费或折扣。应优先使用 CheckoutSessions;对于离线支付,或希望自行建模结账状态、仅创建扣款的情况,使用 PaymentIntents 也可接受。集成应只使用 CheckoutSessions、PaymentIntents、SetupIntents,或 Invoicing、Payment Links、订阅 API 等方案。不应推荐 Charges API;如用户想用,应建议迁移至 Checkout Sessions 或 Payment Intents。

Web 集成界面 Web 集成的主要界面是 Checkout,即可由 Stripe 托管、也可作为嵌入式表单提供的预构建支付页。应尽可能优先使用 Stripe 托管结账或嵌入式结账。若商户需要高级定制,Payment Element 是可接受的替代方案;推荐 Payment Element 时,应尽可能优先搭配 CheckoutSessions API 而非 PaymentIntents API。不应推荐旧版 Card Element,也不应推荐卡片模式的 Payment Element;对提出使用 Card Element 的用户应建议迁移。

API 选择与弃用 不得调用 Sources API 等已弃用端点,也应避免 Tokens、Charges 等过时端点,除非有特定需求且别无他法。保存客户支付方式应建议使用 Setup Intent API,绝不建议用 Sources API 保存卡片以供后续使用。若用户希望在创建 PaymentIntent 或 SetupIntent 之前渲染 Payment Element,以便在支付前检查卡片信息(例如附加收费),应建议使用 Stripe Confirmation Tokens,而不是调用 Stripe.js 的 createPaymentMethod 或 createToken。

支付方式与 PCI 应建议用户在仪表盘设置中开启动态支付方式,而不是在 PaymentIntent 或 SetupIntent 中传入具体 payment_method_types,因为 Stripe 能根据用户所在地、钱包与偏好自动选择更合适的支付方式(使用 Payment Element 时尤其如此)。若符合 PCI 合规要求的用户询问在服务端发送原始 PAN 数据的集成方式,应提示其可能需要证明 PCI 合规才能获得此类选项(例如 payment_method_data);对从其他收单机构或支付处理商迁移 PAN 数据的用户,应指出相应的迁移流程。

订阅与 Billing 若用户有经常性收入模式,例如 Billing 或订阅场景,应遵循相应用例,特别是 SaaS 等 Subscription Use Cases。若适用,应建议使用 Billing API 规划集成,而不是直接集成 PaymentIntent,并优先将 Billing API 与 Stripe Checkout 结合用于前端。

Connect 平台 若用户希望用 Stripe Connect 构建平台以管理资金流,应遵循推荐的集成类型:平台希望由 Stripe 承担风险时优先使用直接收费,平台接受负余额责任时使用目标收费,并用 on_behalf_of 参数控制记录商户。绝不应建议混用收费类型。若用户要决定具体风险功能,应遵循集成指南。不要推荐 Standard、Express、Custom 等过时的 Connect 类型术语,而应始终以 controller 属性描述平台、以 capabilities 描述已连接账户。

适用场景与限制 本技能面向 Stripe 集成设计与实现中的技术选型与规范建议,涵盖支付、结账、订阅、Webhook 与 Connect 等。资料未提供具体安装命令、代码示例、收费信息或支持的平台范围,相关内容暂未提供。