# Elements with Checkout Sessions API ベータ版の変更ログ
Elements with Checkout Sessions API ベータ版実装への変更を追跡します。
> このドキュメントには、 Elements with Checkout Sessions API のベータ版に関連する変更ログが含まれています。
>
> この変更ログは、[Clover](https://docs.stripe.com/changelog/clover.md) 以降を使用している場合には適用されません。代わりに [Stripe 変更ログ](https://docs.stripe.com/changelog.md)を参照してください。
## Clover への移行
### クローバーの変更
- (新機能) [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)をご覧ください。
- (新機能) 決済セッションで設定されると、保存された決済手段が Payment Element で自動的に有効になりました。クライアント側での追加設定は必要ありません。詳細については、[保存された決済手段のデフォルトの動作を更新する](https://docs.stripe.com/changelog/clover/2025-09-30/custom-checkout-saved-payment-method-defaults.md)をご覧ください。
- (新機能) カナダ、イギリス、プエルトリコのカード決済では、郵便番号が自動的に収集されなくなりました。このデータを使用する場合は、[カード決済の郵便番号を削除する](https://docs.stripe.com/changelog/clover/2025-09-30/postal_code_in_card_form_for_non_us_countries.md)をご覧ください。
- (新機能) 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 に移行する前に、まず Basil に[導入を更新](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#migrating-to-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. `initCheckout` に関連する `await` または `.then()` の呼び出しをすべて削除します。
2. `fetchClientSecret` 関数を、Client Secret 文字列または Client Secret 文字列を解決する Promise で置き換えてください。
3. `session()` を置き換える `getSession()` や `confirm()` などのアクションにアクセスするために、新しい非同期関数 `checkout.loadActions()` を呼び出してください。`loadActions()` を一度だけ呼び出す必要があります。
4. 以前に `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 (
);
}
```
詳細については、[Updates initCheckout to be synchronous](https://docs.stripe.com/changelog/clover/2025-09-30/update-init-checkout-synchronous.md) 変更履歴の項目を参照してください。
## Basil への移行
### バジルの変更
- (新機能)[confirm](https://docs.stripe.com/js/custom_checkout/confirm) や [applyPromotionCode](https://docs.stripe.com/js/custom_checkout/apply_promotion_code) などの非同期メソッドは、別のスキーマで解決されます。
- 成功すると、更新されたセッション状態が `session` キーの下に移入されます。以前は、これは `success` キーの下にありました。
- (新機能)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) を渡すとエラーがスローされるようになりました。
- (新機能)確認が成功した後にリダイレクトされた戻り先 URL のクエリパラメータに一貫性がありませんでした。余分なパラメーターは削除され、URL には、Checkout Session の [confirm](https://docs.stripe.com/js/custom_checkout/confirm) または [return_url](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-return_url) の [returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) で指定されたもののみが含まれるようになりました。
- (新機能)サブスクリプションモードセッションの Checkout Session API のレイテンシーを改善し、顧客が最初の決済試行後にセッションを更新できないバグを修正しました
- この変更により、ユーザーが支払いを完了した後にサブスクリプションが作成されるため、`checkout_session.invoice` と `checkout_session.subscription` は Checkout Session が完了するまで null になります。
- 現在、廃止された `payment_intent.invoice` フィールドを使用している場合、`checkout_session.completed` Webhook を使用することで請求書が存在することを確認し、`checkout_session.invoice` または [Invoice Payment リスト](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) をご覧ください。
- 割引を表示するオプションとして、[discountAmounts](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts) に [percentOff](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-discountAmounts-percentOff) を追加しました。
### バジルのアップグレード
Basil に移行する前に、まず[実装を更新](https://docs.stripe.com/checkout/elements-with-checkout-sessions-api/changelog.md#beta-changelog)して `custom_checkout_beta_6` にします。
- Stripe NPM パッケージを使用している場合は、まず `@stripe/stripe-js` を `7.0.0` 以上に、`@stripe/react-stripe-js` を `3.6.0` 以上にアップグレードする必要があります。
- スクリプトタグを使用して Stripe.js を読み込み、まだ `v3` または `acacia` を使用している場合は、次のように[バージョン管理された Stripe.js の命名法](https://docs.stripe.com/sdks/stripejs-versioning.md) を使用して `basil` を参照するようにタグを更新します。
```html
Checkout
```
- Stripe.js の初期化時に Stripe.js ベータヘッダーを削除します。
#### HTML + JS
```js
const stripe = Stripe(
'<>', {
}
);
```
#### React
```javascript
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe("<>", {
});
```
- バックエンド統合で API バージョンのベータヘッダーを削除し、API バージョンを少なくとも `2025-03-31.basil` に指定します。
### Before
#### TypeScript
```typescript
// 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-08-26.dahlia; custom_checkout_beta=v1' as any,
});
```
### After
#### TypeScript
```typescript
// 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,
});
```
## ベータの変更ログ
Elements with Checkout Sessions API ベータでは、次の 2 種類のベータバージョンを使用します。
- フロントエンドのシステムに設定される Stripe.js ベータヘッダー (例: `custom_checkout_beta_6`)。
- バックエンドの導入に設定される、API バージョンのベータヘッダー (例: `custom_checkout_beta=v1`)。
### フロントエンドのベータ版
[Stripe.js を初期化](https://docs.stripe.com/payments/quickstart.md)する際に、フロントエンドのベータバージョンを指定します。
#### custom_checkout_beta_6
Stripe NPM パッケージを使用している場合は、まず `@stripe/stripe-js` を `6.1.0` 以上に、`@stripe/react-stripe-js` を `3.5.0` 以上にアップグレードする必要があります。
- (新機能)[total.appliedBalance](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-total-appliedBalance) の符号が反転しました。正の数は支払われる金額を増やし、負の数は支払われる金額を減らします。
- (新機能) `clientSecret` を [fetchClientSecret](https://docs.stripe.com/js/custom_checkout/init#custom_checkout_init-options-clientSecret) に置き換えました。静的な値を渡す代わりに、クライアントシークレットに async function resolving を渡すように実装を更新します。
- (新機能) Elements メソッドの名前が変更されました。
- React Stripe.js を使用している場合は、`@stripe/react-stripe-js` をアップグレードする以外に何もする必要はありません。
- HTML/JS を使用している場合:
- `createElement('payment')` の代わりに `createPaymentElement()` を使用します。
- `createElement('address', {mode: 'billing'})` の代わりに `createBillingAddressElement()` を使用します。
- `createElement('address', {mode: 'shipping'})` の代わりに `createShippingAddressElement()` を使用します。
- `createElement('expressCheckout')` の代わりに `createExpressCheckoutElement()` を使用します。
- `getElement('payment')` の代わりに `getPaymentElement()` を使用します。
- `getElement('address', {mode: 'billing'})` の代わりに `getBillingAddressElement()` を使用します。
- `getElement('address', {mode: 'shipping'})` の代わりに`getShippingAddressElement()` を使用します。
- `getElement('expressCheckout')` の代わりに `getExpressCheckoutElement()` を使用します。
- (新機能)セッションの状態をより正確に反映するために、確認に関連するフィールドを更新しました。
- [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` を削除しました。
- (新機能) [updateEmail](https://docs.stripe.com/js/custom_checkout/update_email) は、Checkout Session の作成時に [customer_email](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-customer_email) が指定されるとエラーをスローするようになりました。顧客が更新できるメールを事前入力する場合は、`customer_email` を渡す代わりに、ページが読み込まれたらすぐに `updateEmail` を呼び出します。
- (新機能)[returnUrl](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-returnUrl) は絶対 URL である必要があります (たとえば、`/success` のような相対 URL ではなく、`https://` で始まる)。
- (新機能)レンダリングを容易にするため、価格項目をネストされたオブジェクトに更新しました。
- 数値を、`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 に表示しないと、エラーがスローされます。これにより、UI コードの変更を最小限に抑えながら、将来の Stripe 機能の追加など、CheckoutSession の更新時に決済フローページの同期を維持できます。
- 顧客の納税者番号を回収できるようになりました。[納税者番号を回収する方法](https://docs.stripe.com/tax/checkout/tax-ids.md)をご覧ください。
- チェックアウトページの下部にテスト環境専用のアシスタントが表示され、実装のガイダンスと一般的なテストシナリオのショートカットが示されます。
#### custom_checkout_beta_5
- (新機能)`initCustomCheckout` 関数の名前が [initCheckout](https://docs.stripe.com/js/custom_checkout/init) に変更されました。
- React Stripe.js 内では、`CustomCheckoutProvider` は `CheckoutProvider` という名前、`useCustomCheckout` は `useCheckout` という名前に変更されました。
- (新機能) Express Checkout Element を確定するには、[confirm](https://docs.stripe.com/js/custom_checkout/confirm) を呼び出し、[confirm event](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) を `expressCheckoutConfirmEvent` として渡します。
- 以前は、Express Checkout Element の確認は `event.confirm()` を呼び出すことで行われていました。
- (新機能)[confirm](https://docs.stripe.com/js/custom_checkout/confirm) が呼び出されると、Payment Element と Address Element はフォーム入力を検証し、エラーがあればレンダリングします。
- (新機能)エラーメッセージが標準化され、改善されました。
- 関数によって返されるエラーや解決されたエラーは、支払い詳細が無効な場合や残高不足といった既知のシナリオを表します。これらは予測可能な問題であり、決済ページに `message` を表示して顧客に伝えることができます。
- 関数によってスロー/拒否されたエラーは、無効なパラメーターや設定など、インテグレーション自体のエラーを表します。これらのエラーは、顧客に表示するものではありません。
- (新機能)[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` キーの下に入力されます。
- `email`、`phoneNumber`、`billingAddress`、`shippingAddress` オプションを [confirm](https://docs.stripe.com/js/custom_checkout/confirm) に追加しました。
- (新機能)Address Element は、セッションの [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) を呼び出すときにフォームの値が自動的に使用されます。
- 確認前に[変更イベント](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 作成時のオプションとして [fields](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) を追加しました。
- (新機能)無効なオプションを [createElement](https://docs.stripe.com/js/custom_checkout/create_payment_element) に渡すと、エラーがスローされるようになりました。これまで、未確認のオプションは暗黙的に無視されていました。
- (新機能) [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)する方法をご紹介します。
- (新機能) Payment Element のデフォルトの [layout](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-layout) が `accordion` に変更されました。
- 以前のデフォルトレイアウトを引き続き使用するには、`layout='tabs'`を明示的に指定する必要があります。
- (新機能) [confirm](https://docs.stripe.com/js/custom_checkout/confirm) のデフォルトの動作が変更され、確認が成功すると、常に `return_url` にリダイレクトされるようになりました。
- 以前は、顧客がリダイレクトベースの決済手段を選択した場合にのみ `confirm` でリダイレクトしていました。以前の動作を引き続き使用するには、`confirm` に [redirect=‘if_required’](https://docs.stripe.com/js/custom_checkout/confirm#custom_checkout_session_confirm-options-redirect) を渡す必要があります。
#### custom_checkout_beta_2
- (新機能) `lineItem.recurring.interval_count` フィールドは削除され、[lineItem.recurring.intervalCount](https://docs.stripe.com/js/custom_checkout/session_object#custom_checkout_session_object-lineItems-recurring-intervalCount) に置き換えられました。
- (新機能) `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.md#init-stripe)する際に、バックエンドのベータバージョンを指定します。
*バックエンドのベータ版には変更はありません。*