升级 Stripe API 到 2026-09-30.endive：Checkout 的 payment_method_types 没了，SDK 也改了默认校验行为

版本与信源

当前 API 版本 2026-09-30.endive，是第五个以植物命名的重大版本（前四个是 Acacia、Basil、Clover、Dahlia）。Stripe 只在出现破坏性改动时才换大版本名，所以每个植物名版本都对应一次需要动的迁移。

参考文档：

• API changelog：docs.stripe.com/changelog
• upgrades 文档：docs.stripe.com/upgrades
• SDK 迁移指南：github.com/stripe/stripe-python 的 CHANGELOG、github.com/stripe/stripe-node 的 v23 migration guide

直接调 API 的迁移点

Checkout 与 Elements

Checkout Sessions 移除了 payment_method_types 参数。替代方案是改用 dynamic payment methods，或显式传 allowed_payment_method_types / excluded_payment_method_types。

Elements 移除了 paymentMethodTypes 选项，改用 allowedPaymentMethodTypes，或者在 Dashboard 里配置。

Payment Intents、Setup Intents、Payment Methods

Payment Intents 与 Setup Intents 同样移除了 payment method types 参数。

Payment Methods 移除了 PayTo 相关字段。

新增内容

• thin events 对 v1 资源 GA：这是一种版本无关的轻量事件负载，用来简化 webhook 的前向兼容。
• PaymentIntent 对象上新增 Payment Record 属性，不需要再发额外查询。
• 支持 SeQura（西班牙 BNPL）。
• Connect 的 eventually due requirements 现在会报错。

用 SDK 的迁移点

SDK 对应版本是 stripe-python 16.0.0 和 stripe-node v23。破坏点如下：

• 路径参数改为 positional-only，不能再通过关键字传参。
• 移除 StripeObject.request()，改用 StripeClient.raw_request()。
• Reversal 重命名为 TransferReversal。
• 移除 Stripe.ErrorType 命名空间，改用 Stripe.errors。
• verifyHeader / verifyHeaderAsync 默认按 DEFAULT_TOLERANCE 校验时间戳。要保留旧行为，必须显式传 0。
• Node 最低版本升到 20。
• 读取响应体中途断连，改为抛 StripeConnectionError。

其中时间戳校验这一条最容易踩：升级后如果 webhook 签名验证突然开始拒绝请求，先检查是不是默认容差变了，而不是签名密钥配错。

Webhook 的双投递迁移

事件目的地的 snapshot_api_version 独立于 SDK 使用的 API 版本。也就是说，升级 SDK 不会顺带改变事件端点收到的负载版本，两件事要分别处理。

新旧目的地并存期间，Stripe 会对订阅事件做双投递。这意味着 handler 必须幂等，同一条事件可能到达两次，且两次的负载版本可能不同。

升级新端点的做法：

• 对旧版本的请求，忽略其 query 参数并返回 400，让 Stripe 重试。
• 新版本正常处理并返回 200。
• 迁移完成后，禁用旧端点。

强类型语言的限制

Java、Go、.NET 这类强类型语言不能按请求覆盖 API 版本。如果用这些语言的 SDK，版本切换只能通过升级 SDK 本身完成，没法像动态语言那样在单次请求里指定不同版本。