コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要構築済みのシステムをアップグレード
オンライン決済
概要ユースケースを見つけるManaged Payments を使用する
対面決済
決済手段
決済シナリオ
決済以外の機能

メモ

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

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

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

警告

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

すでに Elements with Checkout Sessions API の Clover リリースを使用している場合、この変更ログは適用されません。

Clover への移行

クローバーの変更

  • 新機能 The stripe.initCheckout method is now synchronous instead of asynchronous. This reduces render latency and enables Elements to show skeleton loaders earlier. See Updates initCheckout to be synchronous for migration details.
  • Breaking 決済セッションで設定されると、保存された決済手段が Payment Element で自動的に有効になりました。クライアント側での追加設定は必要ありません。詳細については、保存された決済手段のデフォルトの動作を更新するをご覧ください。
  • Breaking カナダ、イギリス、プエルトリコのカード決済では、郵便番号が自動的に収集されなくなりました。このデータを使用する場合は、カード決済の郵便番号を削除するをご覧ください。
  • Breaking React の実装の場合:
    • インポートパスが @stripe/react-stripe-js から @stripe/react-stripe-js/checkout に変更されました。
    • useCheckout は、エラーをスローする代わりに、非同期状態を示す非合同 ({type: 'loading'}、{type: 'success', checkout: ...} または {type: 'error', error: ...}) を返すようになりました。
    • CheckoutProvider は、initCheckout が成功しなかった場合に、null ではなく無条件に子を表示するようになりました。

クローバーのアップグレード

Clover に移行する前に、まず Basil に導入を更新します。

  • Stripe NPM パッケージを使用している場合は、@stripe/stripe-js を 8.0.0 以上にアップグレードし、@stripe/react-stripe-js を 5.0.0 以上にアップグレードする必要があります。
  • スクリプトタグを使用して Stripe.js を読み込む場合は、次のように Stripe.js のバージョン付き命名規則を使用して、clover を参照するようにタグを更新します。
checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>
  • バックエンドの導入で API バージョンを 2025-09-30.clover 以上に更新します。

導入を次のように更新します。

  1. initCheckout に関連する await または .then() の呼び出しをすべて削除します。
  2. fetchClientSecret 関数を、Client Secret 文字列または Client Secret 文字列を解決する Promise で置き換えてください。
  3. session() を置き換える getSession() や confirm() などのアクションにアクセスするために、新しい非同期関数 checkout.loadActions() を呼び出してください。loadActions() を一度だけ呼び出す必要があります。
  4. 以前に initCheckout を try...catch ブロックでラップした場合、代わりに loadActions() の解決された type の値を調べてエラーをチェックする必要があります。
checkout.js
const clientSecret = fetch("/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
})
  .then((r) => r.json())
  .then((r) => r.clientSecret);

const checkout = await stripe.initCheckout({
  fetchClientSecret: () => clientSecret
});
const checkout = stripe.initCheckout({
  clientSecret
});
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

const session = checkout.session();
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
}

詳細については、Updates initCheckout to be synchronous 変更履歴の項目を参照してください。

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 リストを使用して関連する請求書を見つけることをお勧めします。
    • 詳細については、2025-03-31.basil API変更ログ をご覧ください。
  • 割引を表示するオプションとして、discountAmounts に percentOff を追加しました。

バジルのアップグレード

Basil に移行する前に、まず実装を更新して 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 の命名法 を使用して 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 ベータヘッダーを削除します。
checkout.js
const stripe = Stripe(
  
'pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  betas: ['custom_checkout_beta_6'],
  }
);
  • バックエンド統合で API バージョンのベータヘッダーを削除し、API バージョンを少なくとも 2025-03-31.basil に指定します。
前
後
TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
// 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';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  apiVersion: '2025-11-17.clover; custom_checkout_beta=v1' as any,
});
TypeScript
Node.js
Ruby
PHP
Python
Go
.NET
Java
No results
// 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';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
, {
  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 を初期化 するときにフロントエンドのベータ版を指定します。

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 から読み取ってください。
    • 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 という名前に変更されました。
  • Breaking Express Checkout Element を確定するには、confirm を呼び出し、confirm event を 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

custom_checkout_beta_1

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

バックエンドバージョン

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

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