Stripe 2026-10-28.endive 增量版：Standalone 3DS 事件、纠纷申诉与集成侧要动的几处

2026-10-28.endive 已 GA。这个版本是增量改动，不是破坏性升级：上一个版本 2026-09-30.endive 才包含破坏性变更（从 Checkout Sessions / Payment Intents / Setup Intents 移除 payment_method_types、payment request button 弃用、billing cycle anchor 统一）。所以这次升级的重点不是修调用，而是接住新增能力和新增错误码。

Stripe 按日期给 API 打版本，集成方要固定一个版本，并在请求里带 Stripe-Version，或者在 SDK 初始化时设置；webhook 端点则各自有独立的 API 版本设置。下面按对集成方的影响程度挑几条展开。

1. Standalone 3DS API：新增 webhook 事件与错误消息

Standalone 3DS 独立接入（不走 Payments 的完整支付流程）此前拿不到足够的事件和错误信息，这一版补上了 webhook events 与 error messages 两类内容。

对集成方意味着两件事：

• 事件订阅要补。 3DS 认证状态变化会通过新事件投递，处理逻辑不能只依赖同步返回结果。具体事件名以 changelog / API reference 中该版本列出的事件清单为准，按清单逐个加到端点订阅里，别沿用旧的事件白名单。
• 错误要按 code 分流。 新增错误消息说明失败原因更细了，如果现在只按 HTTP 状态码或单一 decline 文案处理，会把「认证失败」「参数不合法」混在一起。日志里至少落 code 与 message 两个字段，再按 code 决定是重试、跳转重认证还是直接失败。

2. Disputes：证据提交方式、申诉决定、Smart Disputes 校验

纠纷这块有三处改动，都在写入路径上：

• evidence submission method 属性。 Disputes 新增该属性，同时支持在提交时指定 intended submission method，也就是让集成方声明证据打算以什么方式提交，而不是让系统推断。
• 可以提交证据去申诉 dispute decision。 此前 dispute 结论下来后基本只能接受，现在新增了「提交证据以申诉决定」的能力，争议流程的后半段有了接口入口。
• 提交 dispute 时校验 Smart Disputes 可用性。 提交时若 Smart Disputes 不可用会校验失败，需要有一条降级路径：走普通的手工证据提交流程，而不是把整个提交动作卡死在这里。

3. Checkout Sessions 更新时新增 payment intent data 配置

更新 Checkout Session 时可以再传 payment intent data。也就是会话创建完之后，仍有窗口去调整底层 PaymentIntent 相关配置，不用为了改一个字段重建会话。对已经在跑的会话做参数修正时，这条比较实用。

4. Customer Portal：过期会话恢复 + 订阅暂停/恢复

• 过期会话恢复。 用户拿着已过期的 Portal 会话进来时，现在可以恢复，不用强制重新生成链接。
• 订阅暂停。 Portal 里支持暂停订阅，用户可以自助操作，暂停状态会同步到订阅对象上。

这两条都会改变你从 Portal 侧收到的事件量：暂停会带来订阅状态变化，会话恢复会带来新的会话流转，webhook 处理要能识别，不要当成异常。

5. 订阅：billing cycle anchor 与 trial 校验新增错误码

创建或更新订阅时，如果 billing cycle anchor 与 trial 的组合校验不通过，这一版会返回专门的错误码。

上线前要先接住它。顺序建议是：

1. 在测试模式用现有的创建/更新订阅参数组合跑一遍，把该 code 抓到；
2. 检查错误处理里有没有靠 message 文本匹配判定的分支，改成按 code 判断；
3. 再切换 API 版本。否则切完版本，校验从「静默通过」变成「明确报错」，而代码认不出这个 code，会掉进通用错误分支。

6. Klarna / PayPal / Afterpay Clearpay 退款增加 reference 追踪

这三个本地支付方式的退款新增 reference 追踪字段。对账时可以把自家订单号/退款单号带上，退款在 Stripe 侧和渠道侧能对上，减少靠金额加时间戳人工匹配的情况。

7. 保存或扣卡时指定 card-on-file 用途

保存卡片或发起扣款时可以显式指定 card-on-file usage，把「这张卡以什么用途被保存、被扣款」写进请求，而不是留给系统推断。订阅类和重复扣款场景建议显式传。

同一版本里的其它条目

Payments：OUSD 作为 crypto payments 的 token 币种；Payment Links 支持 Scalapay；Checkout Sessions 与 Payment Links 订阅新增 invoice settings 参数；cash balance transactions 新增 RTP 与 FedNow 两种美国银行转账网络类型。

Connect：购买 Terminal 硬件的嵌入式组件、Reporting Chart 嵌入式组件、Accounts v2 API 的 alternative requirements、Accounts v2 的 Global Payouts capabilities。

Tax：博茨瓦纳、加纳、科特迪瓦、毛里求斯税务登记；加纳税种；客户税号类型；博茨瓦纳/加纳/科特迪瓦的 tax ID 支持；Tax Rate 对象上 events 与 ticketing 的 tax type 取值；digital excise tax 与 utility users tax 作为美国登记类型。

Treasury 与资金管理：Inbound Transfers v2 API；Outbound Payments、Payout Intents、Recipient Verifications API；Financial Addresses v2 API；向 Financial Addresses 模拟入账的 sandbox test helper；Received Credits v2 API；交易的 regulatory receipt URL；Global Payouts 的资金管理 API。

Terminal：T600 读卡器；Terminal 配置的 admin menu passcode。

其它：subscriptions、invoicing、Financial Connections 的 semantic thin events；API v2 中 vaulted bank account credentials、payout methods、outbound setup intents；Issuing Cards 的 shipping timestamps。

升级方式

请求版本。 有两种方式：在 SDK 初始化时设版本，或者逐个请求带 header。

Stripe-Version: 2026-10-28.endive

SDK。 升到支持该 API 版本的 SDK release，再用 SDK 里的版本设置项固定，避免默认版本被 SDK 升级顺带改掉。

Webhook 端点。 端点上的 API 版本是独立配置的，改请求 header 不会影响事件负载的渲染版本。要逐个端点确认并更新，特别是这次新增了 Standalone 3DS 事件、订阅暂停、会话恢复相关事件，端点版本落后会拿不到对应结构。

灰度建议

1. 先在 test mode 跑回归，重点覆盖：Standalone 3DS 认证失败路径、dispute 提交（含 Smart Disputes 不可用的降级）、更新 Checkout Session、Portal 过期会话与暂停、订阅创建/更新时的 anchor 与 trial 组合、三种本地支付方式的退款对账、存卡扣款。
2. 把新增错误码（尤其订阅校验那条）先写进代码的兜底分支，再切版本。
3. 生产上先切一个低流量账号或一条 webhook 端点，两个版本并行接收一段时间，对比 payload 差异，尤其是 dispute 与订阅事件的字段。
4. 观察错误率和事件处理失败率稳定后，再全量切请求版本和其余端点。