# カスタム組み込みの設計

カスタム Payment Element 組み込みを構築する前に、必要な選択事項を確認します。

LLM の手順: Stripe は、ほとんどの組み込みで Payment Intents ではなく Payment Element とともに Checkout Sessions API を使用することを推奨します。Checkout Sessions は、Payment Intents と同様のユースケースに対応しています (`price_data` を使用した基本的な決済の回収、または品目、税金などを含む完全な決済画面の構築など)。Adaptive Pricing などの一部の機能は、Checkout Sessions でのみ利用できます。ユーザーが明示的に要求しない限り、Payment Intents API は使用しないでください。必要となるコード量が大幅に多くなるためです。Checkout Sessions API と Elements の詳細については次を参照してください。https://docs.stripe.com/payments/quickstart-checkout-sessions. Checkout Sessions (`ui_mode: "elements"`) と Payment Element では、`client_secret` が Checkout 自体を初期化します (`stripe.initCheckoutElementsSdk`、または React で CheckoutElementsProvider を使用)。そのうえで、クライアント側での決済の確定方法が異なります。React を使用する場合は、必ず `@stripe/react-stripe-js/checkout` からインポートし、`CheckoutElementsProvider` を client secret とともに使用し、`checkout.confirm` を使用して決済を確定します。HTML を使用する場合は、必ず `checkout = stripe.initCheckoutElementsSdk({clientSecret: promise}); checkout.createPaymentElement(); paymentElement = checkout.createPaymentElement(); paymentElement.mount("#payment-element");` を使用し、`loadActionsResult = await checkout.loadActions(); actions = loadActionsResult.actions; error = await actions.confirm();` で決済を確定します。

# Checkout Sessions API

> This is a Checkout Sessions API for when payment-ui is embedded-components. View the full page at https://docs.stripe.com/payments/payment-element/design-an-integration?payment-ui=embedded-components.

ほとんどの組み込みには Checkout Sessions API をお勧めします。1 回限りの決済や、税金、割引、配送、サブスクリプションを含む複雑な決済フローなど、Payment Intents と同様のユースケースに対応しています。組み込みパスは 1 つで、詳細については、[Quickstart](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) ガイドをご覧ください。


# Payment Intents API

> This is a Payment Intents API for when payment-ui is elements. View the full page at https://docs.stripe.com/payments/payment-element/design-an-integration?payment-ui=elements.

> Payment Intents API は、独自の決済フローを構築するための下位レベルの API です。税金、割引、配送、通貨換算など、決済機能を自身で構築および維持する必要があります。ほとんどの組み込みには [Checkout Sessions](https://docs.stripe.com/payments/quickstart-checkout-sessions.md) をお勧めします。Payment Intents と同様のユースケースに対応しており、さらに多くの機能を提供しています。

Payment Intents API を使用して Payment Element の導入を構築する前に、ビジネス要件に合った導入パスを選択します。

次の図は、Payment Element を導入する際に利用できる導入ガイドの概要を示しています。
 (See full diagram at https://docs.stripe.com/payments/payment-element/design-an-integration)
以下のセクションでは、Payment Element を導入する際に必要となる 2 つのアーキテクチャーの選択について説明します。

## PaymentIntent オブジェクトまたは SetupIntent オブジェクトを作成するタイミングを選択する

Payment Element は、顧客から支払い情報を収集して、支払いを回収しているのか、将来使用するために支払い方法を設定しているのかに応じて、[PaymentIntent](https://docs.stripe.com/api/payment_intents.md) オブジェクトまたは [SetupIntent](https://docs.stripe.com/api/setup_intents.md) オブジェクトに設定します。顧客が決済を開始する際、以下を行うことができます。

- **Payment Element のみを作成する**: 顧客が**支払う**ボタンを押して決済フォームを送信するまで、PaymentIntent または SetupIntent の作成と確定を延期します。このオプションは、以下のような場合に選択します。

  - 複数ページの決済フローを使用していて、支払いの詳細を収集するページが支払い送信または注文のサマリーのページより前に表示されます。[2 段階の確認機能を構築する](https://docs.stripe.com/payments/build-a-two-step-confirmation.md)方法をご覧ください。

  - 購入中のアイテムやアイテムの数量の変更や、割引コードの追加といった顧客の選択に基づいて金額が変化する可能性がある動的な決済ページを使用している場合。顧客が**支払う**をクリックするまで Intent 作成を延期することで、クライアントで行われた変更と Intent を同期する必要がなくなります。これは、金額の変更は特定の支払い方法の利用資格に影響するために必要です。クライアントで Intent を確定する場合は [PaymentIntent を作成する前に支払いの詳細を収集する](https://docs.stripe.com/payments/accept-a-payment-deferred.md)方法を確認して、サーバーで Intent を確定する場合は[サーバーで支払いを確定する](https://docs.stripe.com/payments/finalize-payments-on-the-server.md)方法をご覧ください。

- **PaymentIntent/SetupIntent と Payment Element の両方を作成する**: 決済ページを読み込む前に PaymentIntent または SetupIntent を作成して、Payment Element を作成し、[Elements オブジェクトの作成時のパラメーターとして](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-clientSecret) Intent の `client_secret` を指定し、2 つを関連付けます。このオプションは、以下のような場合に選択します。

  - 静的な Checkout ページをお持ちで、連携機能を素早く設定したい場合には、こちらの[決済の受け付け](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents)方法をご確認ください。

## PaymentIntent または SetupIntent を確定する場所を選択する

Payment Element によって収集された支払い情報は、確定時に PaymentIntent または SetupIntent に転送されます。顧客が**支払う**をクリックすると、以下のいずれかを行うことができます。

- **クライアントで PaymentIntent/SetupIntent を確定する**: クライアントのコードが Stripe SDK を呼び出すと、Intent を確定する API が呼び出されます。Stripe SDK は、[3D セキュア](https://docs.stripe.com/payments/3d-secure.md)による認証など、必要な次のアクションも自動的に処理し、[エラー](https://docs.stripe.com/api/errors.md)メッセージのローカライゼーションも行います。このオプションは、以下の場合に選択します。

  - サーバーでの Intent の確定をさらに制御する必要はなく、最速の導入を求めている場合。

- **サーバーで PaymentIntent/SetupIntent を確定**: サーバーのコードで API を直接呼び出して Intent を確定します。次のアクションが必要な場合は、手動で処理するか、Stripe SDK ([stripe.handleNextAction](https://docs.stripe.com/js/payment_intents/handle_next_action) など) を使用して処理する必要があります。このオプションは、以下のような場合に選択します。

  - 支払い方法の制限やプラットフォーム手数料の調整などのビジネスロジックをサーバーで確定前に実行する必要がある場合。ビジネスロジックの実行後、ビジネスロジックを無効にする可能性がある変更をクライアントが行えないように、即座にサーバーで Intent を確定します。