Payment Intents API を利用した Payment Element への移行
単一の Element で、多数の支払い方法を取り扱えます。
注
システムで引き続きトークン付きの Charges API を使用している場合は、まず Payment Intents API への移行ガイドに従ってください。
Stripe Billing、Stripe Tax や割引、配送、通貨換算の使用をご希望の場合
Stripe は現在、サブスクリプション、税金、割引、配送、通貨換算を管理する Payment Element のシステムを開発中です。詳細は、決済ページの構築ガイドをお読みください。
これまでは、支払い方法 (クレジットカード、iDEAL など) ごとに個別の Element が必要でした。Payment Element に移行すると、さまざまな支払い方法を 1 つの Element で受け付けることができます。
PaymentIntnet と SetupIntent にはそれぞれ独自の移行ガイドラインのセットが用意されています。組み込みパスに適したガイド (サンプルコードを含む) を参照してください。
既存のシステムで、Payment Intents API を使用して支払いの作成と追跡を行っているか、または支払い中にカードの詳細を保存している場合、Payment Element を使用するには以下の手順に従います。
支払い方法を有効にする
注意
この導入パスは、Automated Clearing Settlement System (ACSS) を使用する 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.
や stripe.
などの個別の confirm メソッドを使用するのではなく、stripe.confirmPayment を使用し、支払い情報を収集して Stripe に送信します。
PaymentIntent を確定するために、送信ハンドラを次のように更新します。
await elements.
を呼び出してフォーム検証をトリガーし、ウォレット に必要なデータを収集します。submit() - オプション: PaymentIntent の作成を送信ハンドラに移動します。これにより、最終金額が確定している場合にのみ PaymentIntent を作成することになります。
- Payment Element を作成するために使用した
elements
インスタンスとclientSecret
を、PaymentIntent からstripe.
にパラメーターとして渡します。confirmPayment
呼び出されると、stripe.
は 3DS ダイアログの表示による顧客の認証や銀行のオーソリページへのリダイレクトなどの必要なアクションの実行を試みます。確認が完了すると、ユーザーは、設定されている return_
に移動します。これは通常、支払いのステータスを表示するウェブサイトのページに対応しています。
カード支払いで同じ決済フローを維持し、リダイレクトベースの支払い方法の場合にのみリダイレクトを行うようにする場合は、redirect に if_
を設定できます。
以下のコード例では、stripe.
を stripe.
に置き換えています。
// 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_
イベントのほかにこれらのイベントを処理することをお勧めします。
イベント | 説明 | アクション |
---|---|---|
payment_intent.succeeded | 顧客が正常に支払いを完了したときに送信されます。 | 顧客に注文の確定を送信し、顧客の注文のフルフィルメントを実行します。 |
payment_intent.processing | 顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、顧客が口座引き落としを開始するときに送信されます。その後、payment_ イベント、また、失敗の場合は payment_ イベントが送信されます。 | 顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。 |
payment_intent.payment_failed | 顧客が支払いを試みたが、支払いに失敗する場合に送信されます。 | 支払いが processing から payment_ に変わった場合は、顧客に再度支払いを試すように促します。 |
組み込みをテストする
実装内容をテストするためのその他の情報については、テストをご覧ください。