Stripe Node.js SDK v18.1.0-beta.1 版本深度解析

Stripe Node.js SDK 是 Stripe 官方提供的 JavaScript 库，用于在后端 Node.js 应用中与 Stripe API 进行交互。它为开发者提供了便捷的方式来处理支付、订阅、发票等金融业务逻辑。

版本核心变更概述

本次发布的 v18.1.0-beta.1 版本是一个预发布版本，主要带来了 API 版本的更新至 2025-03-31.preview，并引入了多项重要变更和新功能。

重大变更解析

1. 发票支付相关调整：

   • 移除了 InvoicePayment 中的 amount_overpaid 属性
   • 不再支持 out_of_band_payment 和 payment_record 作为发票支付类型
   • InvoicePayment.is_default 类型从可空布尔值变为必填布尔值

2. 结算数据重构：

   • 对 Issuing.Settlement 进行了结构调整，移除了 interchange_fees、net_total 等字段
   • 新增了更详细的结算金额字段如 interchange_fees_amount、net_total_amount 等

3. 终端输入处理优化：

   • 修改了终端设备输入选择的数据结构，从简单的 value 字段变为包含 id 和 text 的完整对象

重要新增功能

1. 余额设置管理：

   • 新增了 BalanceSettings 资源
   • 支持通过 retrieve 和 update 方法管理账户余额设置

2. 外部账户服务：

   • 引入了全新的 ExternalAccountService 类
   • 提供了对卡片和银行账户的统一管理接口
   • 支持创建、删除、列表、检索和更新操作

3. 客户账户标识：

   • 新增了 customer_account 字段，用于标识与各种 Stripe 对象关联的客户账户
   • 这一变更影响了数十个资源类型，为账户管理提供了更清晰的关联关系

4. Stripe 余额支付支持：

   • 新增了对 stripe_balance 支付方式的支持
   • 这一功能扩展了支付选项，允许使用 Stripe 账户余额进行支付

5. 结账会话权限增强：

   • 在结账会话中新增了 update_line_items 和 update_shipping_details 权限
   • 为电商场景提供了更灵活的结账流程控制

创新性功能：Money CardManagement API

本次更新引入了全新的 Money CardManagement API，这是一套面向资金管理的综合解决方案：

1. 核心资源：

   • 金融账户 (FinancialAccount)
   • 金融地址 (FinancialAddress)
   • 入账转账 (InboundTransfer)
   • 出账支付 (OutboundPayment)
   • 出账转账 (OutboundTransfer)

2. 资金流动管理：

   • 支持创建出账支付报价 (OutboundPaymentQuote)
   • 提供完整的转账生命周期管理（创建、取消、列表、检索）
   • 支持出账设置意图 (OutboundSetupIntent) 的更新操作

3. 交易监控：

   • 新增了交易条目 (TransactionEntry) 和交易 (Transaction) 资源
   • 支持对调整 (Adjustment)、收到的贷记 (ReceivedCredit) 等操作的跟踪

4. 事件系统：

   • 引入了丰富的事件类型，覆盖资金流动的各个阶段
   • 包括转账可用、处理中、失败、成功等多种状态事件

账户管理 v2 API 预览

本版本还包含了 Accounts v2 API 的预览功能，为 SaaS 平台提供了更强大的账户管理能力：

1. 账户核心功能：

   • 支持账户的创建、关闭、列表、检索和更新
   • 通过 AccountLink 资源实现账户连接流程

2. 银行账户管理：

   • 针对英国和美国银行账户提供了专门的保管库服务
   • 支持银行账户的确认收款人流程
   • 提供存档和检索功能

3. 人员管理：

   • 新增了 Person 资源，用于管理账户关联人员
   • 支持人员创建、删除和更新事件监控

开发者建议

对于考虑升级到 v18.1.0-beta.1 的开发者，建议注意以下几点：

1. 兼容性检查：

   • 仔细审查重大变更部分，确保现有代码不会受到影响
   • 特别注意发票支付和结算相关接口的变更

2. 新功能评估：

   • Money CardManagement API 提供了完整的资金流动管理方案
   • 评估是否可以将现有资金管理逻辑迁移到新API

3. 测试策略：

   • 由于是预发布版本，建议在测试环境充分验证
   • 特别关注事件系统的变化，确保事件处理逻辑仍然有效

4. 逐步迁移：

   • 对于大型项目，考虑分阶段采用新功能
   • 优先评估 Accounts v2 API 对现有账户体系的影响

这个版本为 Stripe Node.js SDK 带来了显著的功能增强，特别是在资金管理和账户体系方面。开发者可以根据项目需求，选择性地采用这些新功能来构建更强大的支付和金融服务解决方案。