Payment Intents API を利用した Payment Element への移行

支払い方法の設定を表示して、サポートする支払い方法を有効にします。PaymentIntent を作成するには、少なくとも 1 つは支払い方法を有効にする必要があります。

多くの顧客から決済を受け付けられるよう、Stripe では、カードやその他一般的な決済手段がデフォルトで有効になっていますが、ビジネスや顧客に適した追加の決済手段を有効にすることをお勧めします。プロダクトと決済手段のサポートについては決済手段のサポートを、手数料については料金体系ページをご覧ください。

次に、クライアント側のコードを更新して、Elements インスタンスを作成するときに mode、currency、amount を渡します。PaymentIntent で使用する場合は、mode を 'payment' に設定して、currency と amount を将来の顧客への請求内容に設定します。

const stripe =
    Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements();

const stripe =
    Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const options = {
  mode: 'payment',
  currency: 'usd',
  amount: 1099,
};
const elements = stripe.elements(options);

Card Element と個々の支払い方法の Element を Payment Element で置き換えられるようになりました。Payment Element では、支払い方法や国に応じて入力フィールドの収集が自動的に調整されるため (SEPA ダイレクトデビットの請求先住所の収集など)、カスタマイズした入力フィールドを維持する必要がなくなります。

以下は、CardElement を PaymentElement で置き換える例です。

<form id="payment-form">
  <div id="card-element">
  </div>
  <div id="payment-element">
    <!-- Mount the Payment Element here -->
  </div>
  <button id="submit">Submit</button>
</form>

const cardElement = elements.create("card");
cardElement.mount("#card-element");
const paymentElement = elements.create("payment");
paymentElement.mount("#payment-element");

支払いフローで購入者の氏名やメールアドレスなどの詳細がすでに収集されている場合、Payment Element の作成時に fields オプションを渡すことにより、Payment Element によってこの情報が収集されないようにすることができます。特定のフィールドの収集を無効にする場合は、同じデータを stripe.confirmPayment で返す必要があります。

Payment Element では複数の支払い方法を受け付けることができます。支払い方法はダッシュボードで管理できます。Stripe は取引額、通貨、決済フローなどの要素に基づいて、適切な支払い方法が返されるように処理します。購入完了率上昇につながり、購入者の使用通貨と所在地に最も適した支払い方法が優先的に表示されます。

前のステップで Elements グループを作成するときに渡したその他のエレメントオプションも PaymentIntent の作成時に渡す必要があります。

curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-08-27.basil" \
  -d "amount"=1099 \
  -d "currency"="usd" \
  -d "payment_method_types[]"=card \
  -d "automatic_payment_methods[enabled]"=true \

stripe.confirmCardPayment や stripe.confirmP24Payment などの個別の confirm メソッドを使用するのではなく、stripe.confirmPayment を使用し、支払い情報を収集して Stripe に送信します。

PaymentIntent を確定するために、送信ハンドラを次のように更新します。

• await elements.submit() を呼び出してフォーム検証をトリガーし、ウォレット　に必要なデータを収集します。
• オプション: PaymentIntent の作成を送信ハンドラに移動します。これにより、最終金額が確定している場合にのみ PaymentIntent を作成することになります。
• Payment Element を作成するために使用した elements インスタンスと clientSecret を、PaymentIntent から stripe.confirmPayment にパラメーターとして渡します。

呼び出されると、stripe.confirmPayment は 3DS ダイアログの表示による顧客の認証や銀行のオーソリページへのリダイレクトなどの必要なアクションの実行を試みます。確認が完了すると、ユーザーは、設定されている return_url に移動します。これは通常、支払いのステータスを表示するウェブサイトのページに対応しています。

カード支払いで同じ決済フローを維持し、リダイレクトベースの支払い方法の場合にのみリダイレクトを行うようにする場合は、redirect に if_required を設定できます。

以下のコード例では、stripe.confirmCardPayment を stripe.confirmPayment に置き換えています。

// Create the PaymentIntent and obtain clientSecret
const res = await fetch("/create-intent", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
});

const {client_secret: clientSecret} = await res.json();

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  const {error} = await stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card: elements.getElement(CardElement)
    }
  });

  if (error) {
    handleError(error);
  }
};

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the PaymentIntent and obtain clientSecret
  const res = await fetch("/create-intent", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
  });

  const {client_secret: clientSecret} = await res.json();

  // Use the clientSecret and Elements instance to confirm the setup
  const {error} = await stripe.confirmPayment({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
    // Uncomment below if you only want redirect for redirect-based payments
    // redirect: "if_required",
  });

  if (error) {
    handleError(error);
  }
};

支払いが完了すると、Stripe は payment_intent.succeeded イベントを送信します。ダッシュボードの Webhook ツールを使用するか Webhook のガイドに従ってこれらのイベントを受信し、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。

クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアントでは、コールバックが実行される前に顧客がブラウザーのウィンドウを閉じたり、アプリを終了する場合、また悪意を持つクライアントがレスポンスを不正操作する場合もあります。非同期型のイベントをリッスンするよう組み込みを設定すると、単一の組み込みで複数の異なるタイプの支払い方法を受け付けることができます。

Payment Element を使用して支払いを回収する場合は、payment_intent.succeeded イベントのほかにこれらのイベントを処理することをお勧めします。

実装内容をテストするためのその他の情報については、テストをご覧ください。