stripe-node v21 升级：金额字段由 string 改为 Stripe.Decimal，最低 Node 18

迁移文档：stripe-node wiki: Migration guide for v21
API 变更记录：docs.stripe.com/changelog/dahlia

v21 使用 API 版本 2026-03-25.dahlia。Stripe 的版本模型是：大版本以 flora 命名（Acacia、Basil、Clover、Dahlia），包含不向后兼容的改动；每月的版本只包含向后兼容的改动，并沿用上一个大版本的名字。当前版本为 2026-08-26.dahlia。

Node 最低版本提升到 18

低于 18 的 Node.js 不再支持，包要求 Node >= 18。这是最后一个支持 Node 18 的大版本，需要在 2026 年 9 月前迁移到至少 Node 20，理想情况下是 22+。

Decimal 字段改用 Stripe.Decimal，不再用 string

v21 为所有 decimal_string 字段引入了原生 decimal 类型支持。Stripe API 中所有 format: decimal 的字段（例如 unit_amount_decimal、quantity_decimal、fx_rate）在请求参数和响应对象里都从 string 改为 Stripe.Decimal，V1 和 V2 资源均适用。

Stripe.Decimal 是一个内置（vendored）的任意精度 decimal 类型，底层由 BigInt 支撑，没有任何外部依赖。

以下字段在响应对象和请求参数中都发生 string → Stripe.Decimal 的变化：

• Price.unit_amount_decimal
• Price.tiers[].unit_amount_decimal
• Price.currency_options[].tiers[].flat_amount_decimal / unit_amount_decimal
• InvoiceItem.quantity_decimal
• InvoiceItem.pricing.unit_amount_decimal
• InvoiceLineItem.*
• CreditNoteLineItem.unit_amount_decimal
• Checkout.Session.currency_conversion.fx_rate
• Issuing.Authorization 的 fleet 字段（reported_gross_amount_decimal、fuel.quantity_decimal、fuel.unit_cost_decimal 等）

仅出现在请求侧的 decimal 字段同样会变，例如 Subscription、SubscriptionItem、SubscriptionSchedule、Quote、PaymentLink、Invoice line 创建参数中的 price_data.unit_amount_decimal。

BigInt 与 tsconfig

Decimal 内部使用 BigInt。如果代码里直接用 BigInt 字面量（比如把 100n 传给 Decimal.from()），tsconfig.json 的 target 需要设为 ES2020 或更高。如果只用字符串构造（Decimal.from('9.99')），则不需要改 tsconfig.json。

V2 Amount 类型合并

V2 资源此前会为每一个金额属性生成一个独立的 Amount 类（例如 OutboundPayment.Amount、AnnualRevenue.Amount）。这些重复类型现在被合并为单一的共享 Amount 类型。字段本身（value 和 currency）没有变化，只是类型名和 import 路径变了。

2026-03-25.dahlia 的破坏性变更

Elements 与 Stripe.js 相关改动：

• 移除 Stripe.js 中已废弃的方法，用命名更清晰的等价方法替代
• 重命名 Checkout 的初始化方法
• options.layout.radios 不再支持布尔值
• 移除 Stripe.js 中已废弃的 Payment Intents、Setup Intents 和 Sources 方法

错误码重命名（2026-06-24.preview）

/v1/payouts 接口的错误码 storer_capability_missing 和 storer_capability_not_active 被替换为 financial_account_capability_not_enabled 和 financial_account_capability_restricted。如果集成代码按名字处理旧错误码，需要同步更新错误处理逻辑；使用更早 API 版本的集成仍会收到旧的错误码。

后续 SDK 版本的连带变化

stripe-python v15.6.0 / stripe-node v22.6.0 将固定的 API 版本改为 2026-08-26.dahlia，同时 PaymentIntent.allowed_payment_method_types 和 SetupIntent.allowed_payment_method_types 变为必填。

升级步骤

1. 在 Workbench 中查看当前使用的 API 版本
2. 如果使用 SDK，升级到与该 API 版本对应的 SDK 版本
3. 如果不使用 SDK，加上请求头 Stripe-Version: 2026-06-24.preview
4. 升级 webhook 端点使用的 API 版本
5. 测试集成
6. 测试 Connect 集成
7. 在 Workbench 中执行升级（升级后 72 小时内可以回滚版本）