# 具有 Checkout Sessions API Beta 更改日志的 Element
通过 Checkout Sessions API Beta 集成应用跟踪对 Element 的更改。
> 本文档包含与具有 Checkout Sessions API 的 Element Beta 测试版相关的更改日志。
>
> 如果您使用的是 [Clover](https://docs.stripe.com/changelog/clover.md) 或更高版本，则这个更新日志不适用于您。请参阅 [Stripe 更新日志](https://docs.stripe.com/changelog.md)。
## 迁移至 Clover
### Clover 变更
- (Breaking) [stripe.initCheckout](https://docs.stripe.com/js/custom_checkout/init) 方法现在由异步变为同步。这降低了渲染延迟，使 Elements 能够更早显示骨架加载器。请查阅[更新 initCheckout 使其同步](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md)了解迁移详细信息。
- (Breaking) 如果已保存支付方式在 Checkout Session 中进行了配置，则会自动在 Payment Element 中启用，无需额外的客户端配置。请查阅[更新已保存支付方式的默认行为](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md)了解详细信息。
- (Breaking) 加拿大、英国和波多黎各的银行卡支付不再自动收集邮政编码。如果您依赖此数据，请查阅[移除银行卡支付邮政编码](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md)。
- (Breaking) 对于 React 集成：
- 导入路径已从 `@stripe/react-stripe-js` 更改为 `@stripe/react-stripe-js/checkout`。
- [useCheckout](https://docs.stripe.com/js/react_stripe_js/checkout/use_checkout) 现在会返回一个不相交的并集，用于描述异步状态（`{type: 'loading'}`、`{type: 'success', checkout: ...}` 或 `{type: 'error', error: ...}`），而非抛出错误。
- [CheckoutProvider](https://docs.stripe.com/js/react_stripe_js/checkout/checkout_provider) 现在会无条件渲染子组件，而不是在 [initCheckout](https://docs.stripe.com/js/custom_checkout/init) 未成功时渲染 `null`。
### Clover 升级
在迁移到 Clover 之前，请首先将[您的集成更新](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-basil)至 Basil。
- 如果您使用任何 Stripe NPM 包，请务必将 `@stripe/stripe-js` 升级为至少 `8.0.0`，并将 `@stripe/react-stripe-js`升级为至少 `5.0.0`。
- 如果您通过脚本标签加载 Stripe.js，请按如下方式更新标签，即采用[带版本号的 Stripe.js 命名规范](https://docs.stripe.com/sdks/stripejs-versioning.md)，将其指向 `clover`：
```html
Checkout
```
- 请将您后端集成的 API 版本更新为至少 `2025-09-30.clover`。
#### HTML + JS
请按以下方式更新您的集成：
1. 请移除任何 `await` 或与 `initCheckout` 相关的 `.then()` 调用。
1. 请将您的 `fetchClientSecret` 函数替换为客户端密钥字符串，或解析为客户端私钥字符串的 Promise。
1. 调用新的异步函数 `checkout.loadActions()` 以访问操作，例如取代了 `session()` 的 `getSession()`，或 `confirm()`。您只需调用 `loadActions()` 一次。
1. 如果您之前将 `initCheckout` 包裹在 `try...catch` 块中，请改为检查 `loadActions()` 解析后的 `type` 值以检查错误。
```javascript
const clientSecret = fetch("/create-checkout-session", {
method: "POST",
headers: { "Content-Type": "application/json" },
})
.then((r) => r.json())
.then((r) => r.clientSecret);
const checkout = stripe.initCheckout({
clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
const session = loadActionsResult.actions.getSession();
}
```
#### React
请将您的 `@stripe/react-stripe-js` 依赖项升级到至少 `5.0.0` 版本。如果您是从 `4.0.0` 之前的版本升级，请务必阅读 [v4.0.0 发布说明](https://github.com/stripe/react-stripe-js/releases/tag/v4.0.0)，了解额外的迁移步骤。
#### 导入变更
更新您的导入以使用新的结账专用入口点：
```jsx
import {useCheckout, PaymentElement} from '@stripe/react-stripe-js/checkout';
```
#### CheckoutProvider 和 useCheckout 变更
请将 `fetchClientSecret` 替换为 `clientSecret`。现在不必先检查 `useCheckout` 是否返回 `type: 'success'` 即可渲染 Elements，这可降低延迟，并让 Elements 能够更早显示骨架加载器。
```jsx
const App = () => {
const promise = useMemo(() => {
return fetch('/create-checkout-session', {
method: 'POST',
headers: { "Content-Type": "application/json" },
})
.then((res) => res.json())
.then((data) => data.clientSecret);
}, []);
return (
);
}
const CheckoutPage = () => {
const {type, ...rest} = useCheckout();
return (
);
}
```
更多详情请参见“[更新 initCheckout 为同步](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md)”的更新日志条目。
## 迁移到 Basil
### Basil 变更
- (Breaking) 异步方法（如 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 或 [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code)）使用不同的架构进行解析：
- 如果成功，更新的会话状态将填充在 `session` 密钥下。以前是在 `success` 密钥下。
- (Breaking) 现在，如果 Checkout Session 上已设置了 [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url)，那么在 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 上传入 [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) 时会抛出错误。
- (Breaking) 确认成功后重定向到的返回 URL 之前具有不一致的查询参数。现在删除了额外的参数，URL 仅包含在 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 上的 [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) 或 Checkout Session 上的 [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_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](https://docs.stripe.com/api/invoice-payment/list.md) 获取关联账单。
- 要了解更多信息，请阅读[2025-03-31.basil API 更新日志](https://docs.stripe.com/changelog/basil/2025-03-31/checkout-legacy-subscription-upgrade.md)。
- 将 [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) 添加到 [discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts) 作为显示折扣的选项。
### Basil 升级
在迁移到 Basil 之前，首先[将您的集成更新](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog)到 `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 命名规范](https://docs.stripe.com/sdks/stripejs-versioning.md) 将标签更新为引用 `basil` 版本，如下所示：
```html
Checkout
```
- 初始化 Stripe.js 时删除 Stripe.js beta 标头。
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- 删除 API 版本 Beta 标头，并在后端集成指定 API 版本，至少为 `2025-03-31.basil`。
### Before
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2026-04-22.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```javascript
// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
const stripe = new Stripe('<>', {
apiVersion: '2025-03-31.basil' as any,
});
```
## Beta 更改日志
具有 Checkout Sessions API Beta 的 Elements 使用两种 Beta 测试版本：
- 一个Stripe.js Beta 测试头（例如，`custom_checkout_beta_6`），它在您的前端集成设置。
- API 版本 Beta 测试头（例如，`custom_checkout_beta=v1`），该测试头在您的后端集成中设置。
### 前端 Beta 测试版
[初始化 Stripe.js](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) 时指定前端 Beta 测试版本。
#### custom_checkout_beta_6
如果您使用的是任何 Stripe NPM 软件包，则必须先将 `@stripe/stripe-js` 和 `@stripe/react-stripe-js` 至少升级到 `6.1.0` 和 `3.5.0`。
- (Breaking) [total.appliedBalance](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-appliedBalance) 的符号已被翻转。现在，正数会增加支付金额，负数会减少支付金额。
- (Breaking) 将 `clientSecret` 替换成了 [fetchClientSecret](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret)。更新您的集成，将解析的异步函数传递到客户端私钥，而不是传递静态值。
- (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](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) 现在会响应任何挂载的 Billing Address Element 或 Shipping Address Element。
- [canConfirm](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-canConfirm) 在有进行中的确认操作时，现在会变为 `false`。
- 删除了 `confirmationRequirements`。
- (Breaking) 如果在创建 Checkout Session 时提供了 [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email)，则 [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) 现在会引发错误。如果您打算预填充客户可以更新的电子邮件地址，请在页面加载后立即调用 `updateEmail`，而不是传递 `customer_email`。
- (Breaking) [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) 必须是绝对 URL（例如，以 `https://` 开头，而不是以相对 URL 开头，例如 `/success`）。
- (Breaking) 将定价字段更新为嵌套对象，以便于呈现。
- 将数值替换为包含`amount`（格式化的货币字符串，例如 `$10.00`）和 `minorUnitsAmount`（表示货币最小单位值的整数）的对象。如果您已经在读取金额，请改为从 `minorUnitsAmount` 读取。
- 例如，将 `total.total` 替换为 [`total.total.minorUnitsAmount`](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-total-minorUnitsAmount)。
- 您必须从 `checkout` 对象中读取 `total.total.amount` 或 `total.total.minorUnitsAmount` 和 `currency` 和 `minorUnitsAmountDivisor` 中的每一个，并显示在 UI 中，否则会引发错误。这有助于在 CheckoutSession 更新时保持结账页面同步，包括添加未来的 Stripe 功能，且只需最少的 UI 代码更改即可。
- 现在可以收集客户税号了。了解如何[收集税号](https://docs.stripe.com/tax/checkout/tax-ids.md)。
- 现在，结账页面底部提供了一个仅限在测试模式使用的助手，为您提供集成指导，并为常见测试场景提供快捷方式。
#### custom_checkout_beta_5
- (Breaking) `initCustomCheckout` 函数已被重命名为 [initCheckout](https://docs.stripe.com/js/custom_checkout/init)
- 在 React Stripe.js 中，`CustomCheckoutProvider` 被已重命名为 `CheckoutProvider`，`useCustomCheckout` 并被已重命名为 `useCheckout`。
- (Breaking)要确认 Express Checkout Element，请调用[confirm](https://docs.stripe.com/js/custom_checkout/confirm)，并将[确认事件](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event)作为 `expressCheckoutConfirmEvent` 传入。
- 以前，Express Checkout Element 通过调用 `event.confirm()` 来确认。
- (Breaking) 调用 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 时，Payment Element 和 Address Element 将验证表单输入并呈现任何错误。
- (Breaking) 错误消息已进行标准化和改进。
- 函数解决的返回错误/表示已知情况，例如无效的付款详情或资金不足。这些是可预测的问题，可以通过在结账页面上显示 `message` 来传达给您的客户。
- 函数抛出/拒绝执行时返回的错误，代表集成本身出现的错误，如参数无效或配置错误。这些错误不应展示给您的客户。
- (Breaking) 异步方法（如 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 或 [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code)）使用不同的架构进行解析：
- 添加了 `type="success"|"error"`鉴别器字段。
- 如果成功，更新的会话状态将填充在 `success` 密钥下。以前是在 `session` 密钥下。
- 否则，错误将继续填充在 `error` 密钥下。
- 向 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 添加了 `email`、`phoneNumber`、`billingAddress` 和 `shippingAddress` 选项。
- (Breaking) Address Element 不再自动更新 Session 上的 [billingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-billingAddress) 或 [shippingAddress](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-shippingAddress) 字段。
- 只要挂载了 Address Element，调用 [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 时都会自动使用表单值。
- 在确认之前，侦听 [change 事件](https://docs.stripe.com/js/element/events/on_change?type=addressElement) 以使用 Address Element 值。
#### custom_checkout_beta_4
- 向 [Session 对象](https://docs.stripe.com/js/custom_checkout/session_object)添加的 [images](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-images)。
- 在创建 Payment Element 时添加的[字段](https://docs.stripe.com/js/custom_checkout/create_payment_element#custom_checkout_create_payment_element-options-fields)选项。
- 在创建 Express Checkout Element 时添加的 [paymentMethods](https://docs.stripe.com/js/custom_checkout/create_express_checkout_element#custom_checkout_create_express_checkout_element-options-paymentMethods) 选项。
- (Breaking) 现在，将无效选项传递给 [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) 会引发错误。以前，无法识别的选项将被静默忽略。
- (Breaking) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) 和 [updatePhoneNumber](https://docs.stripe.com/js/custom_checkout/update_phone_number) 异步应用更改。在客户完成输入完整的值之前调用这些方法可能会导致性能不佳。
- 不要在每个输入的更改事件上调用 `updateEmail` 或 `updatePhoneNumber`，而应等到客户完成输入时，例如在模糊输入时或提交表单进行付款时。
- `updateEmail` 现在验证输入的信息是否为格式正确的电子邮件地址，如果使用了无效的输入，则返回错误。
- `updatePhoneNumber` 仍然不对输入字符串执行任何验证。
#### custom_checkout_beta_3
- 以下字段已添加到 [Session 对象](https://docs.stripe.com/js/custom_checkout/session_object)：
- [id](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-id)
- [livemode](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-livemode)
- [businessName](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-businessName)
- 现可复用保存的银行卡。了解如何[保存和复用](https://docs.stripe.com/payments/checkout/save-during-payment.md)支付方式。
- (Breaking) Payment Element 的默认 [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) 已更改为 `accordion`。
- 要继续使用以前的默认布局，必须显式指定 `layout='tabs'`。
- (Breaking) [confirm](https://docs.stripe.com/js/custom_checkout/confirm) 的默认行为已更改为在成功确认后始终重定向到您 `return_url`。
- 以前，仅当客户选择基于重定向的支付方式时才会重定向 `confirm`。要继续使用原行为，必须将 [redirect=‘if_required’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) 传递到 `confirm`。
#### custom_checkout_beta_2
- (Breaking)`lineItem.recurring.interval_count` 字段已被删除并替换为 [lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount)。
- (Breaking)`lineItem.amount` 字段已被删除并替换为以下内容：
- [lineItem.amountSubtotal](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountSubtotal)
- [lineItem.amountDiscount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountDiscount)
- [lineItem.amountTaxInclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxInclusive)
- [lineItem.amountTaxExclusive](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-amountTaxExclusive)
#### custom_checkout_beta_1
*这是最初的前端测试版。*
### 后端版本
[设置服务器库时](https://docs.stripe.com/payments/quickstart-checkout-sessions.md#init-stripe)指定后端 Beta 测试版本。
*后端 Beta 测试版没有变化。*