Elements with Checkout Sessions API ベータ版の変更ログ

Elements with Checkout Sessions API ベータ版実装への変更を追跡します。

警告

このドキュメントには、 Elements with Checkout Sessions API のベータ版に関連する変更ログが含まれています。

すでに Elements with Checkout Sessions API の Basil release を使用している場合、このドキュメントは該当しません。

Basil への移行

変更点

新機能confirm や applyPromotionCode などの非同期メソッドは、別のスキーマで解決されます。
- 成功すると、更新されたセッション状態が session キーの下に移入されます。以前は、これは success キーの下にありました。
BreakingCheckout Session で return_url がすでに設定されている場合に、confirm で returnUrl を渡すとエラーがスローされるようになりました。
Breaking確認が成功した後にリダイレクトされた戻り先 URL のクエリパラメータに一貫性がありませんでした。余分なパラメーターは削除され、URL には、Checkout Session の confirm または return_url の returnUrl で指定されたもののみが含まれるようになりました。
Breakingサブスクリプションモードセッションの Checkout Session API のレイテンシーを改善し、顧客が最初の決済試行後にセッションを更新できないバグを修正しました
- この変更により、ユーザーが支払いを完了した後にサブスクリプションが作成されるため、checkout_session.invoice と checkout_session.subscription は Checkout Session が完了するまで null になります。
- 現在、廃止された payment_intent.invoice フィールドを使用している場合、checkout_session.completed Webhook を使用することで請求書が存在することを確認し、checkout_session.invoice または Invoice Payment リストを使用して関連する請求書を見つけることをお勧めします。
- 詳細については、API changelog をご覧ください。
割引を表示するオプションとして、discountAmounts に percentOff を追加しました。

アップグレード

Basil に移行する前に、まず実装を更新して custom_checkout_beta_6 にします。

Stripe NPM パッケージを使用している場合は、まず @stripe/stripe-js を 7.0.0 以上に、@stripe/react-stripe-js を 3.6.0 以上にアップグレードする必要があります。
スクリプトタグを使用して Stripe.js を読み込む場合は、次のようにタグを置き換えて、バージョン管理された Stripe.js を使用するようにスクリプトタグを更新します。

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

Stripe.js の初期化時に Stripe.js ベータヘッダーを削除します。

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

バックエンド統合で API バージョンのベータヘッダーを削除し、API バージョンを少なくとも 2025-03-31.basil に指定します。

前

後

ベータの変更ログ

Elements with Checkout Sessions API ベータでは、次の 2 種類のベータバージョンを使用します。

フロントエンド統合で設定される Stripe.js ベータヘッダー (例: custom_checkout_beta_6)。
バックエンドの実装で設定される API バージョンのベータヘッダー (custom_checkout_beta=v1 など)。

フロントエンドのベータ版

Stripe.js の初期化時にフロントエンドのベータバージョンを指定します。

custom_checkout_beta_6

Stripe NPM パッケージを使用している場合は、まず @stripe/stripe-js を 6.1.0 以上に、@stripe/react-stripe-js を 3.5.0 以上にアップグレードする必要があります。

Breakingtotal.appliedBalance の符号が反転しました。正の数は支払われる金額を増やし、負の数は支払われる金額を減らします。
Breaking clientSecret を fetchClientSecret に置き換えました。静的な値を渡す代わりに、クライアントシークレットに async function resolving を渡すように実装を更新します。
Breaking 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() を使用します。
Breakingセッションの状態をより正確に反映するために、確認に関連するフィールドを更新しました。
- canConfirm は、マウントされた Billing Address Element または Shipping Address Element に応答するようになりました。
- canConfirm は、処理中の確認がある場合に false になるようになりました。
- confirmationRequirements を削除しました。
Breaking updateEmail は、Checkout Session の作成時に customer_email が指定されるとエラーをスローするようになりました。顧客が更新できるメールを事前入力する場合は、customer_email を渡す代わりに、ページが読み込まれたらすぐに updateEmail を呼び出します。
BreakingreturnUrl は絶対 URL である必要があります (たとえば、/success のような相対 URL ではなく、https:// で始まる)。
Breakingレンダリングを容易にするため、価格項目をネストされたオブジェクトに更新しました。
- 数値を、amount ($10.00 などの書式設定された通貨文字列) と minorUnitsAmount (通貨の最小単位で値を表す整数) を含むオブジェクトに置き換えました。すでに金額を読み取っている場合は、代わりに minorUnitsAmount から読み取ってください。
  - たとえば、total.total を total.total.minorUnitsAmount に置き換えます。
- checkout オブジェクトから total.total.amount または total.total.minorUnitsAmount と currency と minorUnitsAmountDivisor をそれぞれ読み取って UI に表示しないと、エラーがスローされます。これにより、UI コードの変更を最小限に抑えながら、将来の Stripe 機能の追加など、CheckoutSession の更新時に決済フローページの同期を維持できます。
顧客の納税番号を収集できるようになりました。納税者番号を収集する方法をご確認ください。
チェックアウトページの下部にテスト環境専用のアシスタントが表示され、実装のガイダンスと一般的なテストシナリオのショートカットが示されます。

custom_checkout_beta_5

BreakinginitCustomCheckout 関数の名前が initCheckout に変更されました。
- React Stripe.js 内では、CustomCheckoutProvider は CheckoutProvider という名前、useCustomCheckout は useCheckout という名前に変更されました。
新機能 Express Checkout Element を確定するには、confirm を呼び出し、confirm イベントを expressCheckoutConfirmEvent として渡します。
- 以前は、Express Checkout Element の確認は event.confirm() を呼び出すことで行われていました。
新機能confirm が呼び出されると、Payment Element と Address Element はフォーム入力を検証し、エラーがあればレンダリングします。
新機能エラーメッセージが標準化され、改善されました。
- 関数によって返されるエラーや解決されたエラーは、支払い詳細が無効な場合や残高不足といった既知のシナリオを表します。これらは予測可能な問題であり、決済ページに message を表示して顧客に伝えることができます。
- 関数によってスロー/拒否されたエラーは、無効なパラメーターや無効な構成など、構築したシステム自体のエラーを表します。これらのエラーは、顧客に表示するためのものではありません。
新機能confirm や applyPromotionCode などの非同期メソッドは、別のスキーマで解決されます。
- type="success"|"error" 識別器フィールドが追加されました。
- 成功すると、更新されたセッション状態が success キーの下に入力されます。以前は、これは session キーの下にありました。
- それ以外の場合、エラーは引き続き error キーの下に入力されます。
email、phoneNumber、billingAddress、shippingAddress オプションを confirm に追加しました。
新機能Address Element は、セッションの billingAddress または shippingAddress フィールドを自動的に更新しなくなりました。
- Address Element がマウントされている限り、confirm を呼び出すときにフォームの値が自動的に使用されます。
- 確認前に変更イベントをリッスンして、Address Element の値を使用します。

custom_checkout_beta_4

Session オブジェクトに images を追加しました。
Payment Element 作成時のオプションとして fields を追加しました。
Express Checkout Element 作成時のオプションとして paymentMethods を追加しました。
Breaking無効なオプションを createElement に渡すと、エラーがスローされるようになりました。これまで、未確認のオプションは暗黙的に無視されていました。
新機能 updateEmail と updatePhoneNumber は、変更を非同期で適用します。顧客が完全な値を入力し終える前にこれらのメソッドを呼び出すと、パフォーマンスが低下する可能性があります。
- 各入力の変更イベントで updateEmail または updatePhoneNumber を呼び出す代わりに、入力をぼかす際や決済するためにフォームを送信したときなど、顧客が入力を完了するタイミングまで待ちます。
- updateEmail は、入力が正しい形式のメールアドレスであることを検証し、無効な入力が使用された場合にエラーを返すようになりました。
- updatePhoneNumber は、入力文字列に対して検証を実行しません。

custom_checkout_beta_3

Session オブジェクトに以下のフィールドが追加されました。
保存したカードを再利用できるようになりました。決済手段を保存して再利用する方法をご紹介します。
新機能 Payment Element のデフォルトの layout が accordion に変更されました。
- 以前のデフォルトレイアウトを引き続き使用するには、layout='tabs'を明示的に指定する必要があります。
新機能 confirm のデフォルトの動作が変更され、確認が成功すると、常に return_url にリダイレクトされるようになりました。
- 以前は、顧客がリダイレクトベースの決済手段を選択した場合にのみ confirm でリダイレクトしていました。以前の動作を引き続き使用するには、confirm に redirect=‘if_required’ を渡す必要があります。

custom_checkout_beta_2

新機能 lineItem.recurring.interval_count フィールドは削除され、lineItem.recurring.intervalCount に置き換えられました。
新機能 lineItem.amount フィールドは削除され、以下に置き換えられました。

custom_checkout_beta_1

これは、フロントエンドの最初のベータ版です。

バックエンドの変更ログ

サーバーライブラリの設定時に、バックエンドのベータ版を指定します。

バックエンドのベータ版には変更はありません。