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

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

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

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

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

const stripe =
    Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');
const options = {
  mode: 'setup',
  currency: 'usd',
};
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.confirmSetup で返す必要があります。

Payment Element では複数の支払い方法を受け付けることができるため、automatic_payment_methods を使用することをお勧めします。有効にすると、Stripe は、顧客が利用できる支払い方法のリストを決定する際に通貨、支払い方法の制限、その他のパラメーターを評価します。コンバージョン率上昇につながり、顧客の使用通貨と所在地に最も適した支払い方法が優先的に表示されます。

SetupIntent を作成するサーバー上のエンドポイントに automatic_payment_methods 属性を追加します。

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

curl https://api.stripe.com/v1/setup_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Version: 2025-08-27.basil" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "automatic_payment_methods[enabled]"=true

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

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

• await elements.submit() を呼び出してフォーム検証をトリガーし、ウォレット　に必要なデータを収集します。
• オプション: SetupIntent の作成を送信ハンドラに移動します。これにより、ユーザーが支払い方法の詳細を送信する準備が整っている場合にのみ SetupIntent を作成することになります。
• Payment Element を作成するために使用した elements インスタンスと clientSecret を、SetupIntent から stripe.confirmSetup にパラメーターとして渡します。

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

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

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

// Create the SetupIntent 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.confirmCardSetup(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 SetupIntent 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.confirmSetup({
    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);
  }
};

テスト用の支払いの詳細とテスト用リダイレクトページを使用して、組み込みを確認できます。以下のタブをクリックすると、各支払い方法の詳細を表示できます。

保存された SEPA デビット PaymentMethod への請求をテストする

iDEAL、Bancontact または Sofort を使用して SetupIntent が確定されると、SEPA ダイレクトデビット の PaymentMethod が生成されます。SEPA ダイレクトデビットは、通知遅延型の決済手段であり、中間の processing 状態に移行してから、数日後に succeeded または requires_payment_method の状態に移行します。