资讯 Stripe Endive 移除 payment_method_types,存量代码要改哪里

2026-11-20 21:05:59

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。

迁移顺序

  1. 在测试账号里把 webhook endpoint 的版本切到新版本,跑一遍事件回放,确认解析逻辑能忽略新增字段和事件类型;
  2. 升级 SDK 版本,按上面的清单改代码,尤其把 payment_method_types / paymentMethodTypes 换成新参数;
  3. 最后切换线上账户的默认 API 版本。

endpoint 固定了自己的版本,所以第 1 步不会影响其他 endpoint;线上默认版本放到最后切,出问题时回退面最小。

复制全文 生成海报 支付 Stripe 接口对接 升级

推荐文章

程序员茄子在线接单