具有 Checkout Sessions API Beta 更改日志的 Element

通过 Checkout Sessions API Beta 集成应用跟踪对 Element 的更改。

警告

本文档包含与具有 Checkout Sessions API 的 Element Beta 测试版相关的更改日志。

如果您已经在使用带有 Checkout Sessions API 的 Basil 版本的 Elements，则本更新日志不适用于您。

迁移到 Basil

更改

Breaking 异步方法（如 confirm 或 applyPromotionCode）使用不同的架构进行解析：
- 如果成功，更新的会话状态将填充在 session 密钥下。以前是在 success 密钥下。
Breaking 现在，如果 Checkout Session 上已设置了 return_url，那么在 confirm 上传入 returnUrl 时会抛出错误。
Breaking 确认成功后重定向到的返回 URL 之前具有不一致的查询参数。现在删除了额外的参数，URL 仅包含在 confirm 上的 returnUrl 或 Checkout Session 上的 return_url 中提供的内容。
Breaking 改进了订阅模式 Session 的 Checkout Session API 延迟，并修复了阻止客户在首次尝试付款后更新会话的错误
- 此更改会在用户完成付款后创建订阅，因此在 Checkout Session 完成之前，checkout_session.invoice 和 checkout_session.subscription 为 null。
- 如果您当前仍在使用已弃用的 payment_intent.invoice 字段，我们建议使用 checkout_session.completed Webhook 来确保账单存在，并通过 checkout_session.invoice 或 Invoice Payment list 获取关联账单。
- 要了解更多信息，请阅读2025-03-31.basil API 更新日志。
将 percentOff 添加到 discountAmounts 作为显示折扣的选项。

升级

在迁移到 Basil 之前，首先将您的集成更新到 custom_checkout_beta_6。

如果您使用的是任何 Stripe NPM 软件包，则必须先将 @stripe/stripe-js 和 @stripe/react-stripe-js 分别至少升级到 7.0.0 和 3.6.0。
如果通过脚本标记加载 Stripe.js，而且仍在使用 v3 或 acacia，请使用版本化 Stripe.js 命名规范将标签更新为引用 basil 版本，如下所示：

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/stripe.js"></script>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

初始化 Stripe.js 时删除 Stripe.js beta 标头。

checkout.js
const stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);

删除 API 版本 Beta 标头，并在后端集成指定 API 版本，至少为 2025-03-31.basil。

升级前

升级后

Beta 更改日志

具有 Checkout Sessions API Beta 的 Elements 使用两种 Beta 测试版本：

Stripe.js Beta 头（例如 custom_checkout_beta_6），在前端集成上设置。
API 版本 Beta 头（例如，custom_checkout_beta=v1），在后端集成上设置。

前端 Beta 测试版

初始化 Stripe.js 时指定前端 Beta 测试版本。

custom_checkout_beta_6

如果您使用的是任何 Stripe NPM 软件包，则必须先将 @stripe/stripe-js 和 @stripe/react-stripe-js 至少升级到 6.1.0 和 3.5.0。

Breaking total.appliedBalance 的符号已被翻转。现在，正数会增加支付金额，负数会减少支付金额。
Breaking 将 clientSecret 替换成了 fetchClientSecret。更新您的集成，将解析的异步函数传递到客户端私钥，而不是传递静态值。
Breaking Elements 方法已重命名。
- 如果您使用的是 React Stripe.js，除了升级 @stripe/react-stripe-js 之外，不需要进行任何操作。
- 如果您使用的是 HTML/JS：
  - 使用 createPaymentElement() 而非 createElement('payment')。
  - 使用 createBillingAddressElement() 而非 createElement('address', {mode: 'billing'})。
  - 使用 createShippingAddressElement() 而非 createElement('address', {mode: 'shipping'})。
  - 使用 createExpressCheckoutElement() 而非 createElement('expressCheckout')。
  - 使用 getPaymentElement() 而非 getElement('payment')。
  - 使用 getBillingAddressElement() 而非 getElement('address', {mode: 'billing'})。
  - 使用 getShippingAddressElement() 而非 getElement('address', {mode: 'shipping'})。
  - 使用 getExpressCheckoutElement() 而非 getElement('expressCheckout')。
Breaking 更新了与确认相关的字段，以更准确地反映会话状态。
- canConfirm 现在会响应任何挂载的 Billing Address Element 或 Shipping Address Element。
- canConfirm 在有进行中的确认操作时，现在会变为 false。
- 删除了 confirmationRequirements。
Breaking 如果在创建 Checkout Session 时提供了 customer_email，则 updateEmail 现在会引发错误。如果您打算预填充客户可以更新的电子邮件地址，请在页面加载后立即调用 updateEmail，而不是传递 customer_email。
Breaking returnUrl 必须是绝对 URL（例如，以 https:// 开头，而不是以相对 URL 开头，例如 /success）。
Breaking 将定价字段更新为嵌套对象，以便于呈现。
- 将数值替换为包含amount（格式化的货币字符串，例如 $10.00）和 minorUnitsAmount（表示货币最小单位值的整数）的对象。如果您已经在读取金额，请改为从 minorUnitsAmount 读取。
  - 例如，将 total.total 替换为 total.total.minorUnitsAmount。
- 您必须从 checkout 对象中读取 total.total.amount 或 total.total.minorUnitsAmount 和 currency 和 minorUnitsAmountDivisor 中的每一个，并显示在 UI 中，否则会引发错误。这有助于在 CheckoutSession 更新时保持结账页面同步，包括添加未来的 Stripe 功能，且只需最少的 UI 代码更改即可。
现在可以收集客户税号了。了解如何收集税号。
现在，结账页面底部提供了一个仅限在测试模式使用的助手，为您提供集成指导，并为常见测试场景提供快捷方式。

custom_checkout_beta_5

Breaking initCustomCheckout 函数已被重命名为 initCheckout
- 在 React Stripe.js 中，CustomCheckoutProvider 被已重命名为 CheckoutProvider，useCustomCheckout 并被已重命名为 useCheckout。
Breaking要确认 Express Checkout Element，请调用confirm，并将确认事件作为 expressCheckoutConfirmEvent 传入。
- 以前，Express Checkout Element 通过调用 event.confirm() 来确认。
Breaking 调用 confirm 时，Payment Element 和 Address Element 将验证表单输入并呈现任何错误。
Breaking 错误消息已进行标准化和改进。
- 函数解决的返回错误/表示已知情况，例如无效的付款详情或资金不足。这些是可预测的问题，可以通过在结账页面上显示 message 来传达给您的客户。
- 被函数拒绝的错误/表示集成本身的错误，例如无效的参数或配置。不应向客户显示这些错误。
Breaking 异步方法（如 confirm 或 applyPromotionCode）使用不同的架构进行解析：
- 添加了 type="success"|"error"鉴别器字段。
- 如果成功，更新的会话状态将填充在 success 密钥下。以前是在 session 密钥下。
- 否则，错误将继续填充在 error 密钥下。
向 confirm 添加了 email、phoneNumber、billingAddress 和 shippingAddress 选项。
Breaking Address Element 不再自动更新 Session 上的 billingAddress 或 shippingAddress 字段。
- 只要挂载了 Address Element，调用 confirm 时都会自动使用表单值。
- 在确认之前，侦听 change 事件以使用 Address Element 值。

custom_checkout_beta_4

向 Session 对象添加的 images。
在创建 Payment Element 时添加的字段选项。
在创建 Express Checkout Element 时添加的 paymentMethods 选项。
Breaking 现在，将无效选项传递给 createElement 会引发错误。以前，无法识别的选项将被静默忽略。
Breaking updateEmail 和 updatePhoneNumber 异步应用更改。在客户完成输入完整的值之前调用这些方法可能会导致性能不佳。
- 不要在每个输入的更改事件上调用 updateEmail 或 updatePhoneNumber，而应等到客户完成输入时，例如在模糊输入时或提交表单进行付款时。
- updateEmail 现在验证输入的信息是否为格式正确的电子邮件地址，如果使用了无效的输入，则返回错误。
- updatePhoneNumber 仍然不对输入字符串执行任何验证。

custom_checkout_beta_3

以下字段已添加到 Session 对象：
现可复用保存的银行卡。了解如何保存和复用支付方式。
Breaking Payment Element 的默认 layout 已更改为 accordion。
- 要继续使用以前的默认布局，必须显式指定 layout='tabs'。
Breaking confirm 的默认行为已更改为在成功确认后始终重定向到您 return_url。
- 以前，仅当客户选择基于重定向的支付方式时才会重定向 confirm。要继续使用原行为，必须将 redirect=‘if_required’ 传递到 confirm。

custom_checkout_beta_2

BreakinglineItem.recurring.interval_count 字段已被删除并替换为 lineItem.recurring.intervalCount。
BreakinglineItem.amount 字段已被删除并替换为以下内容：

custom_checkout_beta_1

这是最初的前端测试版。

后端版本

设置服务器库时指定后端 Beta 测试版本。

后端 Beta 测试版没有变化。