Payment Element に移行する
注
組み込みで引き続きトークン付きの Charges API を使用している場合は、まず Payment Intents API への移行ガイドに従ってください。
Stripe Billing、Stripe Tax や割引、配送、通貨換算の使用をご希望の場合
サブスクリプション、税金、割引、配送、通貨換算を管理する Payment Element のシステムを開発しています。詳細については、決済ページを構築する ガイドをご覧ください。
これまでは、支払い方法 (クレジットカード、iDEAL など) ごとに個別の Element が必要でした。Payment Element に移行すると、さまざまな支払い方法を 1 つの Element で受け付けることができます。
PaymentIntnet と SetupIntent にはそれぞれ独自の移行ガイドラインのセットが用意されています。組み込みパスに適したガイド (サンプルコードを含む) を参照してください。
既存の組み込みで、Payment Intents API を使用して支払いの作成と追跡を行っているか、または支払い中にカードの詳細を保存している場合、Payment Element を使用するには以下の手順に従います。
決済手段を有効にする
注意
現在、この導入パスでは BLIK をサポートしていません。
決済手段の設定を表示して、サポートする決済手段を有効にします。PaymentIntent を作成するには、少なくとも 1 つは決済手段を有効にする必要があります。
Stripe のデフォルトでは、カード支払いとより多くの顧客にアプローチできるその他の一般的な決済手段が有効になっていますが、ビジネスと顧客に適した追加の決済手段を有効にすることをお勧めします。製品と決済手段のサポートについては、決済手段の導入オプションを、手数料については料金体系ページをご覧ください。
Elements インスタンスを更新するクライアント側
次に、クライアント側のコードを更新して、Elements インスタンスを作成するときに mode
、currency
、amount
を渡します。PaymentIntent で使用する場合は、mode
を 'payment'
に設定して、currency
と amount
を将来の顧客への請求内容に設定します。
Payment Element を追加するクライアント側
Card Element と個々の決済手段の Element を Payment Element で置き換えられるようになりました。Payment Element では、決済手段や国に応じて入力フィールドの収集が自動的に調整されるため (SEPA ダイレクトデビットの請求先住所の収集など)、カスタマイズした入力フィールドを維持する必要がなくなります。
以下は、CardElement
を PaymentElement
で置き換える例です。
支払いフローで購入者の氏名やメールアドレスなどの詳細がすでに収集されている場合、Payment Element の作成時に fields オプションを渡すことにより、Payment Element によってこの情報が収集されないようにすることができます。特定のフィールドの収集を無効にする場合は、同じデータを stripe.confirmPayment で返す必要があります。
PaymentIntent 作成コールを更新するサーバー側
Payment Element では複数の決済手段を受け付けることができます。決済手段はダッシュボードで管理できます。Stripe は取引額、通貨、決済フローなどの要素に基づいて、適切な決済手段が返されるように処理します。購入完了率上昇につながり、購入者の使用通貨と所在地に最も適した決済手段が優先的に表示されます。
前のステップで Elements グループを作成するときに渡したその他のエレメントオプションも PaymentIntent の作成時に渡す必要があります。
注意
各決済手段は PaymentIntent で渡された通貨をサポートしている必要があり、ビジネスは、各決済手段を使用できる国のいずれかに所在する必要があります。サポート内容の詳細については、決済手段の導入オプションのページをご覧ください。
送信ハンドラーを更新するクライアント側
stripe.confirmCardPayment
や stripe.confirmP24Payment
などの個別の confirm メソッドを使用するのではなく、stripe.confirmPayment を使用し、支払い情報を収集して Stripe に送信します。
PaymentIntent を確定するために、送信ハンドラを次のように更新します。
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
イベントのほかにこれらのイベントを処理することをお勧めします。
イベント | 説明 | アクション |
---|---|---|
payment_intent.succeeded | 顧客が正常に支払いを完了したときに送信されます。 | 顧客に注文の確定を送信し、顧客の注文のフルフィルメントを実行します。 |
payment_intent.processing | 顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、顧客が口座引き落としを開始するときに送信されます。その後、payment_intent.succeeded イベント、また、失敗の場合は payment_intent.payment_failed イベントが送信されます。 | 顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。 |
payment_intent.payment_failed | 顧客が支払いを試みたが、支払いに失敗する場合に送信されます。 | 支払いが processing から payment_failed に変わった場合は、顧客に再度支払いを試すように促します。 |
組み込みをテストする
実装内容をテストするためのその他の情報については、テストをご覧ください。