Stripe Endive 移除 payment_method_types,存量代码要改哪里
Endive 是 Stripe flora 版本模型里的第五个大版本。首发版本 2026-09-30.endive 同时带有破坏性变更和新功能,之后的小版本只做增量。此前的大版本依次是 Acacia、Basil、Clover、Dahlia,当前版本为 2026-11-18.endive。
- 变更日志:
- 版本说明:
- 全部版本:
版本模型:月度只加不改,半年一次破坏性变更
从 2024-09-30.acacia 起,Stripe 每月发布一个不含破坏性变更的 API 版本,升级不需要改代码;每半年一次大版本,其首个版本带破坏性变更,升级可能需要改代码。
API 版本决定以下几件事:不设 Stripe-Version 时能发哪些参数、收到什么结构的对象;Stripe.js 返回对象的结构;发往 webhook endpoint 的事件对象结构;自动化的 Billing 操作。
版本来源的优先级:请求头 Stripe-Version > 服务端 SDK 固定的版本 > 账户默认版本。账户默认版本在首次 API 请求时确定,可在 Workbench 查看和升级;sandbox 的默认版本与 live 账户相互独立。取回事件时,事件结构由事件发生时账户的默认 API 版本决定。
webhook endpoint 可以单独固定自己的 API 版本,Stripe 始终按该版本序列化后发给这个 endpoint。这一点直接影响迁移顺序。
Endive 对 payment method types 的删除
Payments 侧最需要注意的是三处移除:
- Checkout Sessions 的
payment_method_types参数被删除; - Elements 的
paymentMethodTypes选项被删除; - PaymentIntent 和 SetupIntent 的 payment method types 参数被删除。
替代方案:Checkout 改用 dynamic payment methods,或用 allowed_payment_method_types / excluded_payment_method_types;Elements 改用 allowedPaymentMethodTypes,或在 Dashboard 里配置支付方式。
同一个版本里还有若干相关变更:弃用 payment request button;移除 Payment Method 上 PayTo 专属字段;Payment Evaluation 的 signal score 改为可空;BLIK 失败返回具体 decline code;新增 Standalone 3D Secure API、SeQura 支持、BLIK recurring off-session、日本的 PayPay 支持;allowed payment method types 加入 card-present 支付方式;Payment Intent 增加 Payment Record 属性;Payment Record 增加 3DS 2.3.0/2.3.1 版本。Connect、Billing、Treasury、Financial Connections 各有小改动,例如 Account Links v2 移除 configurations、Account v2 capability 新增 rejected 状态、统一 billing cycle anchor 格式、Reserve Release 的 reason 枚举改名、Financial Connections 的 countries 过滤器改名为 country。
兼容性约定
以下属于兼容变更,接收端必须能承受:新增 API 资源、新增可选请求参数、响应新增属性、属性顺序变化、opaque 字符串长度或格式变化(包括增删 ch_ 之类前缀)、新增事件类型。
因此解析逻辑要忽略不认识的字段和事件类型,不能做严格校验。另外对象 ID 最长可达 255 字符,MySQL 存储用 VARCHAR(255) COLLATE utf8_bin。
thin events
针对 v1 资源的 thin events 已经 GA,payload 轻量且与版本无关,适合做前向兼容的 webhook 集成。2026-11-18 又为 subscriptions、invoicing、Financial Connections 加了 semantic thin events:如果原来订阅宽泛的 *.updated 再自行过滤具体变化,可以改为订阅 semantic events。
stripe-node v23
v23 使用 API 版本 2026-09-30.endive,迁移点包括:
- 最低 Node 20;
- V2 的 list 方法返回
Stripe.V2List,只带next_page_url/previous_page_url; - V2 请求使用按操作区分的 address 接口;
Stripe.ErrorType移除,改用Stripe.errors;- 顶层
stripe.constructEventWithoutVerification()移除,改用stripe.webhooks.constructEventWithoutVerification(); - 不完整的响应体改为抛
StripeConnectionError,不再是StripeAPIError; verifyHeader/verifyHeaderAsync默认使用Webhook.DEFAULT_TOLERANCE,要跳过时间戳容差需显式传0。
迁移顺序
- 在测试账号里把 webhook endpoint 的版本切到新版本,跑一遍事件回放,确认解析逻辑能忽略新增字段和事件类型;
- 升级 SDK 版本,按上面的清单改代码,尤其把
payment_method_types/paymentMethodTypes换成新参数; - 最后切换线上账户的默认 API 版本。
endpoint 固定了自己的版本,所以第 1 步不会影响其他 endpoint;线上默认版本放到最后切,出问题时回退面最小。