Strip API Dahlia（2026-03-25.dahlia）升级：破坏性变更清单与回滚窗口

• Changelog：
• 升级指南：
• 版本策略：
• SDK 版本策略：

版本模型

Dahlia 是 flora 命名版本模型中的第四个 release。首个版本 2026-03-25.dahlia 同时引入破坏性变更与新特性，后续 Dahlia 版本只包含增量变更。此前的 release 依次为 Acacia、Basil、Clover；每次引入破坏性变更，版本就进入下一个 release 名。

自 2024-09-30.acacia 起，Stripe 每月发布一个无破坏性变更的新 API 版本，每半年发布一个新的破坏性 release。SDK 随每月 API 版本出 minor，随半年破坏性 release 出 major。当前版本为 2026-08-26.dahlia，另有 preview 通道 2026-05-27.preview。

Dahlia 主要破坏性变更

Elements 与 Stripe.js。 移除了 Stripe.js 中的弃用方法，改用命名更清晰、功能更好的等价方法；同时重命名了 Checkout 的初始化方法。集成里凡是调用这些旧方法名的位置都要替换，改名后的方法不会保留别名。

Payment Intent / Setup Intent。 changelog 中列出的破坏性条目包括：Removes support for specifying payment method types in Payment Intents and Setup Intents（Payments，Breaking）。也就是说，创建或更新这两类对象时不能再指定支付方式类型。

同一批 changelog 里还有一条 Global Payouts 相关的破坏性条目：Updates bank account and payout method resources for Global Payouts（Breaking）。

新特性

• UPI 支付方式：印度实时支付，支持一次性支付与订阅。
• Issuing：可配置虚拟 Issuing 卡在完成指定次数支付后自动取消。
• Checkout Sessions：可用 integration identifier 对 Checkout Session 分组和追踪；更新了 Checkout Session UI mode 的枚举值；在以订阅方式付款时，可为待处理发票项配置计费间隔。
• 发票小数数量：创建/更新 Invoice Item 与 Invoice Line Item 时支持小数数量，最多 12 位小数精度。

升级操作

版本号控制什么。 API 版本控制你看到的 API 与 webhook 行为：请求可以带哪些参数、响应里会出现哪些属性。版本在首次发起 API 请求时设定。

不带 Stripe-Version 头时，请求走账户默认版本；每次请求显式带 Stripe-Version 头即可测试新版本。建议在代码里显式指定集成的 API 版本，而不是依赖账户默认值——否则账户默认版本一变，线上行为就跟着变。

升级与回滚。 升级在 Workbench 里操作。升级完成后 72 小时内可以安全回滚到升级前的版本。

被视为向后兼容的变更。 判断集成是否会被无意中打坏，先看下面这些 Stripe 视为兼容的情况：

• 新增资源
• 新增可选请求参数
• 响应新增属性
• 响应属性顺序变化
• opaque 字符串（对象 ID、错误消息）的长度或格式变化，包括增删固定前缀（如 ch_）
• 新增事件类型

前两类意味着请求侧一般安全；后几类意味着解析侧必须宽容。对象 ID 最长可能到 255 字符，所以存储层要按这个长度设计——例如用 MySQL 存 ID，用 VARCHAR(255) COLLATE utf8_bin 列。webhook 监听器同样要优雅处理不认识的事件类型，不能因为收到新 event type 就报错中断。

SDK 强类型。 stripe-java、stripe-go、stripe-dotnet 的请求固定在其版本发布时的最新 API 版本。想切换 API 版本，必须升级或降级 SDK 版本，不能只改请求头。