Checkout Sessions API を使用した Payment Element へ移行する

決済手段の設定を表示して、対応する予定の決済手段を有効にします。Checkout セッションを作成するには、決済手段を 1 つ以上有効にする必要があります。

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

2025-03-31.basil API バージョン以降を使用するよう SDK を設定します。

// 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,
});

Payment Element では複数の決済手段を受け付けられるため、Checkout Session に payment_method_types を渡さないと自動的に有効になる dynamic payment メソッドを使用することをお勧めします。これを有効にすると、Stripe は通貨、決済手段の制限、その他のパラメーターを評価して、顧客が利用できる決済手段のリストを決定します。購入完了率が高く、顧客の通貨と場所に最も関連性の高い決済手段を優先します。

代わりに、PaymentIntent 作成コールを更新して Checkout Session を作成します。Checkout Sessions インスタンスでは、以下を渡します。

• line_items:注文の内容を表します
• ui_mode: custom: 埋め込みコンポーネントを使用していることを示します
• mode: payment:Checkout Session の 1 回限りの支払いを受け付けることを示します
• return_url顧客が決済手段のアプリまたはサイトで決済を認証またはキャンセルした後にリダイレクトされる URL を表します。

さらに、Checkout Session の client_secret をクライアント側に返して、後で使用するようにします。

各 Checkout Session は、確認時に PaymentIntent を生成します。PaymentIntent の作成時に現在の実装から追加のパラメータを保持する場合は、payment_intent_data で使用可能なオプションを参照してください。

intent = Stripe::PaymentIntent.create({
  amount: 1099,
  currency: 'usd',
  payment_method_types: ['card'],
})

session = Stripe::Checkout::Session.create({
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {name: 'T-shirt'},
        unit_amount: 1099,
      },
      quantity: 1,
    },
  ],
  mode: 'payment',
  ui_mode: 'custom',
  return_url: '{{RETURN_URL}}',
})

{
  clientSecret: session.client_secret,
}.to_json

埋め込みコンポーネントに移行するには、顧客のメールを収集する追加の手順が必要です。

<input type="text" id="email" />
<div id="email-errors"></div>

const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    actions.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
}

Card Element と個々の payment メソッドの 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 = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

stripe.confirmCardPayment や stripe.confirmP24Payment などの個別の確認方法を使用する代わりに、checkout.confirm を使用して決済情報を収集し、Stripeに送信します。

Checkout Session を確定するには、個々の confirm メソッドの代わりに checkout.confirm を使用するように送信ハンドラを更新します。

呼び出されると、checkout.confirm は、3DS ダイアログを表示したり、銀行のオーソリページにリダイレクトしたりするなど、必要なアクションの完了を試みます。確認が完了すると、顧客は設定したreturn_url にリダイレクトされます。これは通常、決済のステータスを提供するウェブサイトのページに対応します。

カード決済で同じ決済フローを維持し、リダイレクトベースの決済手段でのみリダイレクトする場合は、redirect を if_required に設定できます。

次のコード例では、stripe.confirmCardPayment を checkout.confirm に置き換えています。

// 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);

  const {error} = await checkout.confirm();

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

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

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

Payment Element を使用して支払いを収集する場合は、checkout.session.completed イベントの他にこれらのイベントを処理することをお勧めします。

1. 決済ページに移動します。
2. 次の表の決済手段を使用して、支払いの詳細を入力します。カード支払いの場合:
   • カードの有効期限として任意の将来の日付を入力します。
   • 任意の 3 桁のセキュリティコードを入力します。
   • 請求先の任意の郵便番号を入力します。
3. Stripe に決済を送信します。
4. ダッシュボードに移動し、取引ページで決済を探します。決済が成功していると、そのリストに表示されます。
5. 決済をクリックすると、請求先情報や購入したアイテムのリストなどの詳細が表示されます。この情報を使用して注文のフルフィルメントを実行できます。

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