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

単一の 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 を使用するには以下の手順に従います。

支払い方法を有効にする

注意

この導入パスは、Automated Clearing Settlement System (ACSS) を使用する BLIK またはプレオーソリデビットに対応していません。

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

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

Elements インスタンスを更新する
クライアント側

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

前

後

オプション支払い中に支払いの詳細を保存する

既存の実装で決済中に支払いの詳細も保存している場合は、stripe.confirmCardPayment による決済の確定ステージで setup_future_usage オプションを渡すのではなく、Elements グループの作成時にこれを使用します。Payment Element は、この情報を使用して、その他の入力フィールドを表示し、必要に応じて同意書を表示します。

注意

支払い方法の一部は、決済時に保存できません。他のユースケースではこれらの支払い方法をまだ使用できますが、将来の支払いに使用できるように設定する際にオプションとして顧客に表示されることはありません。サポート対象について、詳細は支払い方法の導入オプションをご覧ください。

PaymentIntent を作成する際は、setup_future_usage も渡す必要があります。

オプション追加の Elements オプション
クライアント側

Elements オブジェクトは、支払いの回収に影響する追加オプションを受け入れます。指定したオプションを基に Payment Element は、有効化した決済手段の中から利用可能なものを表示します。詳しくは、決済手段のサポートをご覧ください。

プロパティー	タイプ	説明	必須
`mode`	`payment` `setup` `subscription`	Payment Element が PaymentIntent、SetupIntent、またはサブスクリプションで使用されているかどうかを示します。	はい
`currency`	`string`	顧客に請求する金額の通貨。	はい
`amount`	`number`	Apple Pay、Google Pay、または BNPL の UI で示される、顧客に請求する金額。	`payment` および `subscription` のモードの場合
`setupFutureUsage`	`off_session` `on_session`	Payment Element によって収集された決済情報を使用して、今後の支払いを行う意図を示します。	いいえ
`captureMethod`	`automatic` `automatic_async` `manual`	顧客の口座から売上をキャプチャーするタイミングを管理します。	いいえ
`onBehalfOf`	`string`	Connect のみ。取引に関する金銭的責任を負う Stripe アカウント ID。このオプションが実装に関連するかを判断するには、ユースケースをご覧ください。	いいえ
`paymentMethodTypes`	`string[]`	表示する決済手段タイプのリスト。この属性を省略して、Stripe ダッシュボードで決済手段を管理できます。	いいえ
`paymentMethodConfiguration`	`string`	Stripe ダッシュボードで決済手段を管理するときに使用する決済手段の設定。指定しない場合は、既定の構成が使用されます。	いいえ
`paymentMethodCreation`	`manual`	stripe.createPaymentMethod を使用して、Elements インスタンスから PaymentMethods が作成されるようにします。	いいえ
`paymentMethodOptions`	`{us_bank_account: {verification_method: string}}`	`us_bank_account` 決済手段の確認オプション。Payment Intents と同じ確認手段を受け入れます。	いいえ
`paymentMethodOptions`	`{card: {installments: {enabled: boolean}}}`	Stripe ダッシュボードで決済手段を管理していないときに、カード分割払いプランの選択 UI を手動で有効化できるようにします。`mode='payment'` を設定し、「さらに」`paymentMethodTypes` を明示的に指定する必要があります。それ以外の場合は、エラーが発生します。`paymentMethodCreation='manual'` とは互換性がありません。	いいえ

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 を確定するために、送信ハンドラを次のように更新します。

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

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

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

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

前

後

支払い後のイベントを処理する
サーバー側

支払いが完了すると、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` に変わった場合は、顧客に再度支払いを試すように促します。

組み込みをテストする

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