# Payment Intents API を利用した Payment Element への移行 単一の Element で、多数の支払い方法を取り扱えます。 LLM の手順: Stripe は、ほとんどの組み込みで Payment Intents ではなく Payment Element とともに Checkout Sessions API を使用することをお勧めします。Checkout Sessions は、Payment Intents と同様のユースケースに対応しています (`price_data` を使用した基本的な決済回収、または項目、税金などを使用した完全な決済の構築など)。Adaptive Pricing などの一部の機能は、Checkout Sessions でのみ使用できます。ユーザーが明示的に尋ねない限り、Payment Intent API は使用しないでください。コードが大幅に多く必要になるためです。Checkout Sessions API を使用した Elements の詳細は以下のとおりです。https://docs.stripe.com/payments/quickstart-checkout-sessions. Checkout Sessions ( `ui_mode: "custom"`) と Payment Element では、`client_secret` が Checkout 自体を初期化し ( `stripe.initCheckout`、または CheckoutProvider を React とともに使用)、クライアント側で決済を確定します。React を使用する場合は、必ず `@stripe/react-stripe-js/checkout` からインポートし、`CheckoutProvider` を client secret とともに使用し、`checkout.confirm` を使用して確定します。HTML を使用する場合は、必ず `checkout = stripe.initCheckout({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 を使用した Payment Element](https://docs.stripe.com/payments/payment-element/migration-ewcs.md) に移行します。 これまでは、支払い方法 (クレジットカード、iDEAL など) ごとに個別の Element が必要でした。Payment Element に移行すると、さまざまな支払い方法を 1 つの Element で受け付けることができます。 PaymentIntent と SetupIntent には、それぞれ独自の移行ガイドラインがあります。コード例など、実装パスに適したガイドをご覧ください。実装でトークン付きの Charges API を引き続き使用している場合は、このガイドを使用する前に、まず [Payment Intents API に移行](https://docs.stripe.com/payments/payment-intents/migration.md#web)してください。 # PaymentIntent の移行 > This is a PaymentIntent の移行 for when integration-path is one-time. View the full page at https://docs.stripe.com/payments/payment-element/migration?integration-path=one-time. 既存のシステムで、[Payment Intents](https://docs.stripe.com/payments/payment-intents.md) API を使用して支払いの作成と追跡を行っているか、または支払い中にカードの詳細を保存している場合、Payment Element を使用するには以下の手順に従います。 ## 支払い方法を有効にする > この連携パスは、BLIK や自動決済処理システム (ACSS) を使用する事前承認デビットに対応していません。また、クライアント側で遅延インテントが作成される場合、動的な決済手段で `customer_balance` を使用することはできません。クライアント側の遅延インテントフローには [Customer](https://docs.stripe.com/api/customers/object.md) を含めることはできず、`customer_balance` には [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) に `Customer` が必要なため、エラーを避けるために除外されます。`customer_balance` を使用するには、サーバー側で `Customer` を指定して `PaymentIntent` を作成し、その `client_secret` をクライアントに返します。 [支払い方法の設定](https://dashboard.stripe.com/settings/payment_methods)を表示して、サポートする支払い方法を有効にします。*PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) を作成するには、少なくとも 1 つは支払い方法を有効にする必要があります。 多くの顧客から決済を受け付けられるよう、Stripe では、カードやその他一般的な決済手段がデフォルトで有効になっていますが、ビジネスや顧客に適した追加の決済手段を有効にすることをお勧めします。プロダクトと決済手段のサポートについては[決済手段のサポート](https://docs.stripe.com/payments/payment-methods/payment-method-support.md)を、手数料については[料金体系ページ](https://stripe.com/pricing/local-payment-methods)をご覧ください。 ## Elements インスタンスを更新する [クライアント側] 次に、クライアント側のコードを更新して、Elements インスタンスを作成するときに `mode`、`currency`、`amount` を渡します。PaymentIntent で使用する場合は、`mode` を `'payment'` に設定して、`currency` と `amount` を将来の顧客への請求内容に設定します。 #### Javascript ### Before ```javascript const stripe = Stripe('<>'); const elements = stripe.elements(); ``` ### After ```javascript const stripe = Stripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099, }; const elements = stripe.elements(options); ``` #### React ### Before ```jsx const stripePromise = loadStripe('<>'); function App() { return ( ); }; ``` ### After ```jsx const stripePromise = loadStripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099, }; function App() { return ( ); }; ``` ## Optional: 支払い中に支払いの詳細を保存する 既存の実装で決済中に支払いの詳細も保存している場合は、`stripe.confirmCardPayment` による決済の確定ステージで `setup_future_usage` オプションを渡すのではなく、Elements グループの作成時にこれを使用します。Payment Element は、この情報を使用して、その他の入力フィールドを表示し、必要に応じて同意書を表示します。 > 支払い方法の一部は、決済時に保存できません。他のユースケースではこれらの支払い方法をまだ使用できますが、将来の支払いに使用できるように設定する際にオプションとして顧客に表示されることはありません。サポート対象について、詳細は[支払い方法の導入オプション](https://docs.stripe.com/payments/payment-methods/integration-options.md)をご覧ください。 #### Javascript ```javascript const stripe = Stripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099,setup_future_usage: 'off_session', }; const elements = stripe.elements(options); ``` #### React ```jsx const stripePromise = loadStripe('<>'); const options = { mode: 'payment', currency: 'usd', amount: 1099,setup_future_usage: 'off_session', }; function App() { return ( ); }; ``` PaymentIntent を作成する際は、`setup_future_usage` を渡します。 #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -d "customer"="{{CUSTOMER_ID}}" \-d "setup_future_usage"= "off_session" \ -d "amount"=1099 \ -d "currency"="usd" \ ``` ## Optional: 追加の Elements オプション [クライアント側] [Elements オブジェクト](https://docs.stripe.com/js/elements_object/create_without_intent)は、支払いの回収に影響する追加オプションを受け入れます。指定したオプションを基に Payment Element は、有効化した決済手段の中から利用可能なものを表示します。詳しくは、[決済手段のサポート](https://docs.stripe.com/payments/payment-methods/payment-method-support.md)をご覧ください。 指定する Elements オプション ( `captureMethod`、`setupFutureUsage`、`paymentMethodOptions` など) が、Intent の作成時および確定時に渡す同等のパラメーターと一致していることを確認してください。パラメーターが一致しないと、予期しない動作やエラーが発生する可能性があります。 | プロパティー | タイプ | 説明 | 必須 | | ---------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `mode` | - `payment` - `setup` - `subscription` | Payment Element が *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods)、*SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method)、または*サブスクリプション* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)で使用されているかどうかを示します。 | はい | | `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。このオプションが実装に関連するかを判断するには、[ユースケース](https://docs.stripe.com/connect/charges.md)をご覧ください。 | いいえ | | `paymentMethodTypes` | `string[]` | 表示する決済手段タイプのリスト。この属性を省略して、[Stripe ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で決済手段を管理できます。 | いいえ | | `paymentMethodConfiguration` | `string` | [Stripe ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で決済手段を管理するときに使用する[決済手段の設定](https://docs.stripe.com/api/payment_method_configurations.md)。指定しない場合は、既定の構成が使用されます。 | いいえ | | `paymentMethodCreation` | `manual` | [stripe.createPaymentMethod](https://docs.stripe.com/js/payment_methods/create_payment_method_elements) を使用して、Elements インスタンスから PaymentMethods が作成されるようにします。 | いいえ | | `paymentMethodOptions` | `{us_bank_account: {verification_method: string}}` | `us_bank_account` 決済手段の確認オプション。[Payment Intents](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-us_bank_account-verification_method) と同じ確認手段を受け入れます。 | いいえ | | `paymentMethodOptions` | `{card: {installments: {enabled: boolean}}}` | [Stripe ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で決済手段を管理していないときに、カード分割払いプランの選択 UI を手動で有効化できるようにします。`mode='payment'` を設定し、「さらに」`paymentMethodTypes` を明示的に指定する必要があります。それ以外の場合は、エラーが発生します。`paymentMethodCreation='manual'` とは互換性がありません。 | いいえ | ## Payment Element を追加する [クライアント側] [React Stripe.js](https://github.com/stripe/react-stripe-js) を使用している場合、Payment Element を使用するために最新のパッケージに更新してください。 Card Element と個々の支払い方法の Element を Payment Element で置き換えられるようになりました。Payment Element では、支払い方法や国に応じて入力フィールドの収集が自動的に調整されるため (SEPA ダイレクトデビットの請求先住所の収集など)、カスタマイズした入力フィールドを維持する必要がなくなります。 以下は、`CardElement` を `PaymentElement` で置き換える例です。 #### JavaScript ```html
``` ```javascript const paymentElement = elements.create("payment"); paymentElement.mount("#payment-element"); ``` 支払いフローで購入者の氏名やメールアドレスなどの詳細がすでに収集されている場合、Payment Element の作成時に [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) オプションを渡すことにより、Payment Element によってこの情報が収集されないようにすることができます。特定のフィールドの収集を無効にする場合は、同じデータを [stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) で返す必要があります。 ## PaymentIntent 作成コールを更新する [サーバー側] Payment Element では複数の支払い方法を受け付けることができます。支払い方法は[ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で管理できます。Stripe は取引額、通貨、決済フローなどの要素に基づいて、適切な支払い方法が返されるように処理します。購入完了率上昇につながり、購入者の使用通貨と所在地に最も適した支払い方法が優先的に表示されます。 前のステップで Elements グループを作成するときに渡したその他のエレメントオプションも PaymentIntent の作成時に渡す必要があります。 #### curl ```bash curl https://api.stripe.com/v1/payment_intents \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -d "amount"=1099 \ -d "currency"="usd" \-d "automatic_payment_methods[enabled]"=true \ ``` > 各決済手段は PaymentIntent で渡された通貨に対応している必要があり、ビジネスは各決済手段がサポートする国のいずれかに所在する必要があります。対応状況の詳細については、[決済手段の導入オプション](https://docs.stripe.com/payments/payment-methods/integration-options.md)をご覧ください。 ## 送信ハンドラーを更新する [クライアント側] `stripe.confirmCardPayment` や `stripe.confirmP24Payment` などの個別の confirm メソッドを使用するのではなく、[stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) を使用し、支払い情報を収集して Stripe に送信します。 PaymentIntent を確定するために、送信ハンドラを次のように更新します。 - `await elements.submit()` を呼び出してフォーム検証をトリガーし、[ウォレット](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-wallets)　に必要なデータを収集します。 - オプション: PaymentIntent の作成を送信ハンドラに移動します。これにより、最終金額が確定している場合にのみ PaymentIntent を作成することになります。 - Payment Element を作成するために使用した `elements` インスタンスと `clientSecret` を、PaymentIntent から `stripe.confirmPayment` にパラメーターとして渡します。 呼び出されると、`stripe.confirmPayment` は 3DS ダイアログの表示による顧客の認証や銀行のオーソリページへのリダイレクトなどの[必要なアクション](https://docs.stripe.com/payments/paymentintents/lifecycle.md)の実行を試みます。確認が完了すると、ユーザーは、設定されている `return_url` に移動します。これは通常、[支払いのステータスを表示](https://docs.stripe.com/payments/accept-a-payment.md#web-post-payment)するウェブサイトのページに対応しています。 カード支払いで同じ決済フローを維持し、リダイレクトベースの支払い方法の場合にのみリダイレクトを行うようにする場合は、[redirect](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) に `if_required` を設定できます。 以下のコード例では、`stripe.confirmCardPayment` を `stripe.confirmPayment` に置き換えています。 ### Before ```javascript // 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); if (error) { handleError(error); } }; ``` ### After ```javascript 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); } }; ``` ## Optional: CVC を再収集する 保存されたクレジットカードで以降の支払いを作成する際には、不正利用の追加対策としてカードのセキュリティコードを再収集して、ユーザーを確認することをお勧めします。 まず、サーバーで金額、通貨、[顧客](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) ID、および [require_cvc_recollection](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-card-require_cvc_recollection) を指定して PaymentIntent を作成します。*Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) に関連付けられた *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) を[一覧表示](https://docs.stripe.com/api/payment_methods/list.md)して、CVC の再収集に表示する PaymentMethod を決定します。 PaymentIntent の Client Secret をブラウザーに渡したら、クライアント側で Stripe Elements を使用して CVC 情報を再収集できます。`cardCvc` Element を使用してユーザーから CVC 値を再収集し、次に [stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) を使用してクライアントからの決済を確定します。`payment_method` を PaymentMethod ID に、`payment_method_options[card][cvc]` を `cardCvc` Element に設定します。 ```javascript const result = await stripe.confirmCardPayment(clientSecret, { payment_method: '{{PAYMENT_METHOD_ID}}', payment_method_options: { card: { cvc: cardCvcElement } }, }); if (result.error) { // Show error to your customer console.log(result.error.message); } else { if (result.paymentIntent.status === 'succeeded') { // Show a success message to your customer // There's a risk of the customer closing the window before callback // execution. Set up a webhook or plugin to listen for the // payment_intent.succeeded event that handles any business critical // post-payment actions. } } ``` セキュリティコードの確認に失敗しても支払いが成功することがあります。これを防ぐには、セキュリティコードの確認に失敗した支払いをブロックする [Radar ルール](https://docs.stripe.com/radar/rules.md#traditional-bank-checks)を設定します。 ## 支払い後のイベントを処理する [サーバー側] 支払いが完了すると、Stripe は [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) イベントを送信します。[ダッシュボードの Webhook ツール](https://dashboard.stripe.com/webhooks)を使用するか [Webhook のガイド](https://docs.stripe.com/webhooks/quickstart.md)に従ってこれらのイベントを受信し、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。 クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアントでは、コールバックが実行される前に顧客がブラウザーのウィンドウを閉じたり、アプリを終了する場合、また悪意を持つクライアントがレスポンスを不正操作する場合もあります。非同期型のイベントをリッスンするよう組み込みを設定すると、単一の組み込みで[複数の異なるタイプの支払い方法](https://stripe.com/payments/payment-methods-guide)を受け付けることができます。 Payment Element を使用して支払いを回収する場合は、`payment_intent.succeeded` イベントのほかにこれらのイベントを処理することをお勧めします。 | イベント | 説明 | アクション | | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded) | 顧客が正常に支払いを完了したときに送信されます。 | 顧客に注文の確定を送信し、顧客の注文の*フルフィルメント* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)を実行します。 | | [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing) | 顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、顧客が口座引き落としを開始するときに送信されます。その後、`payment_intent.succeeded` イベント、また、失敗の場合は `payment_intent.payment_failed` イベントが送信されます。 | 顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。 | | [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | 顧客が支払いを試みたが、支払いに失敗する場合に送信されます。 | 支払いが `processing` から `payment_failed` に変わった場合は、顧客に再度支払いを試すように促します。 | ## 組み込みをテストする #### カード | カード番号 | シナリオ | テスト方法 | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | 4242424242424242 | カード支払いは成功し、認証は必要とされません。 | クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。 | | 4000002500003155 | カード支払いには*認証* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase)が必要です。 | クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。 | | 4000000000009995 | カードは、`insufficient_funds` などの拒否コードで拒否されます。 | クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。 | | 6205500000000000004 | UnionPay カードは、13 ～ 19 桁の可変長です。 | クレジットカード番号と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。 | #### ウォレット | 決済手段 | シナリオ | テスト方法 | | ------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Alipay | 顧客はリダイレクトベースの[即時通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の支払い方法で支払いに成功します。 | リダイレクトベースの任意の支払い方法を選択し、必要な情報を入力して、支払いを確定します。その後、リダイレクトページで **Complete test payment (テスト支払い完了)** をクリックします。 | #### 銀行へのリダイレクト | 決済手段 | シナリオ | テスト方法 | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | BECS ダイレクトデビット | 顧客が BECS ダイレクトデビットによる支払いに成功しました。 | アカウント番号 `900123456` と BSB `000000` を使用して、フォームに入力します。確定された PaymentIntent のステータスは、まず `processing` に移行し、3 分後に `succeeded` ステータスに移行します。 | | BECS ダイレクトデビット | 顧客の支払いが `account_closed` エラーコードで失敗します。 | アカウント番号 `111111113`と BSB `000000`を使用して、フォームに入力します。 | | Bancontact、EPS、iDEAL、Przelewy24 | 顧客は、リダイレクトベースの即時通知型の支払い方法のリダイレクトページで、認証に失敗しました。 | リダイレクトベースの任意の支払い方法を選択し、必要な情報を入力して、支払いを確定します。その後、リダイレクトページで **Fail test payment (テスト支払い失敗)** をクリックします。 | | Pay by Bank | 顧客はリダイレクトベースの、[遅延通知型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の支払い方法で支払いに成功します。 | 支払い方法を選択し、必要な情報を入力して、支払いを確定します。その後、リダイレクトページで **Complete test payment (テスト支払い完了)** をクリックします。 | | Pay by Bank | 顧客は、リダイレクトベースの遅延通知型の支払い方法のリダイレクトページで、認証に失敗しました。 | 支払い方法を選択し、必要な情報を入力して、支払いを確定します。その後、リダイレクトページで **Fail test payment (テスト支払いを失敗させる)** をクリックします。 | | BLIK | BLIK による支払いはさまざまな理由で失敗します。即時の失敗 (コードの有効期限切れや無効など)、遅延型のエラー (銀行による拒否など)、またはタイムアウト (顧客が時間内に応答しなかったなど) などがあります。 | メールパターンを使用して[さまざまな失敗をシミュレーションします。](https://docs.stripe.com/payments/blik/accept-a-payment.md#simulate-failures) | #### 口座引き落とし | 決済手段 | シナリオ | テスト方法 | | -------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | SEPA ダイレクトデビット | 顧客が SEPA ダイレクトデビットによる支払いに成功しました。 | 口座番号 `AT321904300235473204` を使用して、フォームに入力します。確定された PaymentIntent のステータスはまず、processing に移行し、3 分後に succeeded ステータスに移行します。 | | SEPA ダイレクトデビット | 顧客の Payment Intent のステータスが、`processing` から `requires_payment_method` に移行します。 | 口座番号 `AT861904300235473202` を使用して、フォームに入力します。 | #### 店舗支払い | 決済手段 | シナリオ | テスト方法 | | ----------- | ------------------------------------- | ------------------------------------------------------------- | | Boleto、OXXO | 顧客が Boleto または OXXO で取引の詳細を使用して支払います。 | 支払い方法として Boleto または OXXO を選択し、支払いを送信します。ダイアログが表示されたら、それを閉じます。 | 実装内容をテストするためのその他の情報については、[テスト](https://docs.stripe.com/testing.md)をご覧ください。 # SetupIntent の移行 > This is a SetupIntent の移行 for when integration-path is future. View the full page at https://docs.stripe.com/payments/payment-element/migration?integration-path=future. 既存のシステムで、将来の支払いに備えて [Setup Intents](https://docs.stripe.com/payments/setup-intents.md) API を使用している場合に Payment Element を使用するには、以下の手順に従います。 ## 支払い方法を有効にする > この連携パスは、BLIK や自動決済処理システム (ACSS) を使用する事前承認デビットに対応していません。また、クライアント側で遅延インテントが作成される場合、動的な決済手段で `customer_balance` を使用することはできません。クライアント側の遅延インテントフローには [Customer](https://docs.stripe.com/api/customers/object.md) を含めることはできず、`customer_balance` には [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) に `Customer` が必要なため、エラーを避けるために除外されます。`customer_balance` を使用するには、サーバー側で `Customer` を指定して `PaymentIntent` を作成し、その `client_secret` をクライアントに返します。 [支払い方法の設定](https://dashboard.stripe.com/settings/payment_methods)を表示して、サポートする支払い方法を有効にします。*SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method) を作成するには、少なくとも 1 つは支払い方法を有効にする必要があります。 多くの顧客から決済を受け付けられるよう、Stripe では、カードやその他一般的な決済手段がデフォルトで有効になっていますが、ビジネスや顧客に適した追加の決済手段を有効にすることをお勧めします。プロダクトと決済手段のサポートについては[決済手段のサポート](https://docs.stripe.com/payments/payment-methods/payment-method-support.md)を、手数料については[料金体系ページ](https://stripe.com/pricing/local-payment-methods)をご覧ください。 ## Elements インスタンスを更新する [クライアント側] 次に、クライアント側のコードを更新して、Elements インスタンスを作成するときに `mode` と `currency` を渡します。SetupIntent で使用する場合は、`mode` を `'setup'` に設定して、`currency` を将来の顧客への請求内容に設定します。 #### Javascript ### Before ```javascript const stripe = Stripe('<>'); const elements = stripe.elements(); ``` ### After ```javascript const stripe = Stripe('<>'); const options = { mode: 'setup', currency: 'usd', }; const elements = stripe.elements(options); ``` #### React ### Before ```jsx const stripePromise = loadStripe('<>'); function App() { return ( ); }; ``` ### After ```jsx const stripePromise = loadStripe('<>'); const options = { mode: 'setup', currency: 'usd', }; function App() { return ( ); }; ``` ## Optional: 追加の Elements オプション [クライアント側] [Elements オブジェクト](https://docs.stripe.com/js/elements_object/create_without_intent)は、支払いの回収に影響する追加オプションを受け入れます。指定したオプションを基に Payment Element は、有効化した決済手段の中から利用可能なものを表示します。詳しくは、[決済手段のサポート](https://docs.stripe.com/payments/payment-methods/payment-method-support.md)をご覧ください。 指定する Elements オプション ( `captureMethod`、`setupFutureUsage`、`paymentMethodOptions` など) が、Intent の作成時および確定時に渡す同等のパラメーターと一致していることを確認してください。パラメーターが一致しないと、予期しない動作やエラーが発生する可能性があります。 | プロパティー | タイプ | 説明 | 必須 | | ---------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `mode` | - `payment` - `setup` - `subscription` | Payment Element が *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods)、*SetupIntent* (The Setup Intents API lets you build dynamic flows for collecting payment method details for future payments. It tracks the lifecycle of a payment setup flow and can trigger additional authentication steps if required by law or by the payment method)、または*サブスクリプション* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)で使用されているかどうかを示します。 | はい | | `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。このオプションが実装に関連するかを判断するには、[ユースケース](https://docs.stripe.com/connect/charges.md)をご覧ください。 | いいえ | | `paymentMethodTypes` | `string[]` | 表示する決済手段タイプのリスト。この属性を省略して、[Stripe ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で決済手段を管理できます。 | いいえ | | `paymentMethodConfiguration` | `string` | [Stripe ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で決済手段を管理するときに使用する[決済手段の設定](https://docs.stripe.com/api/payment_method_configurations.md)。指定しない場合は、既定の構成が使用されます。 | いいえ | | `paymentMethodCreation` | `manual` | [stripe.createPaymentMethod](https://docs.stripe.com/js/payment_methods/create_payment_method_elements) を使用して、Elements インスタンスから PaymentMethods が作成されるようにします。 | いいえ | | `paymentMethodOptions` | `{us_bank_account: {verification_method: string}}` | `us_bank_account` 決済手段の確認オプション。[Payment Intents](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-us_bank_account-verification_method) と同じ確認手段を受け入れます。 | いいえ | | `paymentMethodOptions` | `{card: {installments: {enabled: boolean}}}` | [Stripe ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で決済手段を管理していないときに、カード分割払いプランの選択 UI を手動で有効化できるようにします。`mode='payment'` を設定し、「さらに」`paymentMethodTypes` を明示的に指定する必要があります。それ以外の場合は、エラーが発生します。`paymentMethodCreation='manual'` とは互換性がありません。 | いいえ | ## Payment Element を追加する [クライアント側] [React Stripe.js](https://github.com/stripe/react-stripe-js) を使用している場合、Payment Element を使用するために最新のパッケージに更新してください。 Card Element と個々の支払い方法の Element を Payment Element で置き換えられるようになりました。Payment Element では、支払い方法や国に応じて入力フィールドの収集が自動的に調整されるため (SEPA ダイレクトデビットの請求先住所の収集など)、カスタマイズした入力フィールドを維持する必要がなくなります。 以下は、`CardElement` を `PaymentElement` で置き換える例です。 #### JavaScript ```html
``` ```javascript const paymentElement = elements.create("payment"); paymentElement.mount("#payment-element"); ``` 支払いフローで購入者の氏名やメールアドレスなどの詳細がすでに収集されている場合、Payment Element の作成時に [fields](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-fields) オプションを渡すことにより、Payment Element によってこの情報が収集されないようにすることができます。特定のフィールドの収集を無効にする場合は、同じデータを [stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) で返す必要があります。 ## SetupIntent 作成コールを更新する [サーバー側] Payment Element では複数の支払い方法を受け付けることができるため、`automatic_payment_methods` を使用することをお勧めします。有効にすると、Stripe は、顧客が利用できる支払い方法のリストを決定する際に通貨、支払い方法の制限、その他のパラメーターを評価します。コンバージョン率上昇につながり、顧客の使用通貨と所在地に最も適した支払い方法が優先的に表示されます。 SetupIntent を作成するサーバー上のエンドポイントに `automatic_payment_methods` 属性を追加します。 前のステップで Elements グループを作成するときに渡したその他のエレメントオプションも SetupIntent の作成時に渡す必要があります。 #### curl ```bash curl https://api.stripe.com/v1/setup_intents \ -u <>: \ -H "Stripe-Version: 2026-02-25.clover" \ -d "customer"="{{CUSTOMER_ID}}" \-d "automatic_payment_methods[enabled]"=true ``` > 一部の支払い方法は、将来の支払いのために保存できません。詳細については、[支払い方法の導入オプション](https://docs.stripe.com/payments/payment-methods/integration-options.md)をご覧ください。 ## 送信ハンドラーを更新する [クライアント側] `stripe.confirmCardSetup` や `stripe.confirmP24Setup` などの個別の confirm メソッドを使用するのではなく、[stripe.confirmSetup](https://docs.stripe.com/js/setup_intents/confirm_setup) を使用し、支払い情報を収集して Stripe に送信します。 SetupIntent を確定するために、送信ハンドラを次のように更新します。 - `await elements.submit()` を呼び出してフォーム検証をトリガーし、[ウォレット](https://docs.stripe.com/js/elements_object/create_payment_element#payment_element_create-options-wallets)　に必要なデータを収集します。 - オプション: SetupIntent の作成を送信ハンドラに移動します。これにより、ユーザーが支払い方法の詳細を送信する準備が整っている場合にのみ SetupIntent を作成することになります。 - Payment Element を作成するために使用した `elements` インスタンスと `clientSecret` を、SetupIntent から `stripe.confirmSetup` にパラメーターとして渡します。 呼び出されると、`stripe.confirmSetup` は 3DS ダイアログの表示による顧客の認証や、銀行のオーソリページへのリダイレクトなどの[必要なアクション](https://docs.stripe.com/payments/paymentintents/lifecycle.md)の完了を試みます。確認が完了すると、ユーザーは構成した `return_url` にリダイレクトされます。これは通常、`SetupIntent` のステータスを提供するウェブサイト上のページに対応します。 カード支払いの詳細の保存で同じフローを維持し、リダイレクトベースの支払い方法の場合にのみリダイレクトを行うようにする場合は、[redirect](https://docs.stripe.com/js/setup_intents/confirm_setup#confirm_setup_intent-options-redirect) に `if_required` を設定します。 以下のコード例では、`stripe.confirmCardSetup` を `stripe.confirmSetup` に置き換えています。 ### Before ```javascript // Create the SetupIntent 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); if (error) { handleError(error); } }; ``` ### After ```javascript 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 SetupIntent 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.confirmSetup({ 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); } }; ``` ## 組み込みをテストする テスト用の支払いの詳細とテスト用リダイレクトページを使用して、組み込みを確認できます。以下のタブをクリックすると、各支払い方法の詳細を表示できます。 #### カード | 決済手段 | シナリオ | テスト方法 | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | クレジットカード | カードの設定は成功し、*認証* (Strong Customer Authentication (SCA) is a regulatory requirement in effect as of September 14, 2019, that impacts many European online payments. It requires customers to use two-factor authentication like 3D Secure to verify their purchase)は必要ありません。 | クレジットカード番号 `4242 4242 4242 4242` と、任意の有効期限、セキュリティーコード、郵便番号を使用してクレジットカードフォームに入力します。 | | クレジットカード | このカードは初期設定時に認証が必要であり、それ以降は支払いに成功します。 | クレジットカード番号 `4000 0025 0000 3155` と、任意の有効期限、セキュリティーコード、郵便番号を使用してクレジットカードフォームに入力します。 | | クレジットカード | このカードは、初期設定時も、以降の支払いでも認証が必要です。 | クレジットカード番号 `4000 0027 6000 3184` と、任意の有効期限、セキュリティーコード、郵便番号を使用してクレジットカードフォームに入力します。 | | クレジットカード | 設定中にカードは拒否されます。 | クレジットカード番号 `4000 0000 0000 9995` と、任意の有効期限、セキュリティーコード、郵便番号を使用してクレジットカードフォームに入力します。 | #### 銀行へのリダイレクト | 決済手段 | シナリオ | テスト方法 | | -------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | Bancontact | 顧客は、Bancontact を使用して、今後の使用に備えた SEPA ダイレクトデビットによる支払い方法の設定を完了しました。 | Bancontact フォームで任意の氏名を使用して、リダイレクトページで **Authorize test setup (テスト設定承認)** をクリックします。 | | Bancontact | 顧客は Bancontact リダイレクトページで認証に失敗します。 | Bancontact フォームで任意の氏名を使用して、リダイレクトページで **Fail test setup (テスト設定失敗)** をクリックします。 | | BECS ダイレクトデビット | 顧客が BECS ダイレクトデビットによる支払いに成功しました。 | 口座番号 `900123456` を使用して、フォームに入力します。確定された PaymentIntent のステータスは、まず `processing` に移行し、3 分後に `succeeded` ステータスに移行します。 | | BECS ダイレクトデビット | 顧客の支払いが `account_closed` エラーコードで失敗します。 | 口座番号 `111111113` を使用して、フォームに入力します。 | | iDEAL | 顧客は iDEAL を使用して、今後の使用に備えて [SEPA ダイレクトデビット](https://docs.stripe.com/payments/sepa-debit.md)による決済手段の設定を完了しました。 | iDEAL フォームで任意の氏名と銀行を使用し、リダイレクトページで **Authorize test setup (テスト設定承認)** をクリックします。 | | iDEAL | 顧客は iDEAL リダイレクトページで認証に失敗します。 | iDEAL フォームで任意の銀行を選択し、任意の氏名を指定して、リダイレクトページで **Fail test setup (テスト設定失敗)** をクリックします。 | #### 口座引き落とし | 決済手段 | シナリオ | テスト方法 | | -------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | SEPA ダイレクトデビット | 顧客が SEPA ダイレクトデビットによる支払いに成功しました。 | 口座番号 `AT321904300235473204` を使用して、フォームに入力します。確定された PaymentIntent のステータスはまず、processing に移行し、3 分後に succeeded ステータスに移行します。 | | SEPA ダイレクトデビット | 顧客の Payment Intent のステータスは、`processing` から `requires_payment_method` に移行します。 | 口座番号 `AT861904300235473202` を使用して、フォームに入力します。 | ### 保存された SEPA デビット PaymentMethod への請求をテストする iDEAL、Bancontact または Sofort を使用して SetupIntent が確定されると、[SEPA ダイレクトデビット](https://docs.stripe.com/payments/sepa-debit.md) の *PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が生成されます。SEPA ダイレクトデビットは、[通知遅延型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であり、中間の `processing` 状態に移行してから、数日後に `succeeded` または `requires_payment_method` の状態に移行します。 #### メール `payment_method.billing_details.email` を以下のいずれかの値に設定して、`PaymentIntent` のステータス遷移をテストしてください。任意のテキストとアンダースコアをメールアドレスの前に追加することもできます。例えば、`test_1_generatedSepaDebitIntentsFail@example.com` を使用すると、`PaymentIntent` で使用した際に必ず失敗する SEPA ダイレクトデビットの PaymentMethodになります。 | メールアドレス | 説明 | | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | `generatedSepaDebitIntentsSucceed@example.com` | `PaymentIntent` のステータスが `processing` から `succeeded` に遷移します。 | | `generatedSepaDebitIntentsSucceedDelayed@example.com` | `PaymentIntent` のステータスが 3 分後に `processing` から `succeeded` に遷移します。 | | `generatedSepaDebitIntentsFail@example.com` | `PaymentIntent` のステータスが `processing` から `requires_payment_method` に遷移します。 | | `generatedSepaDebitIntentsFailDelayed@example.com` | `PaymentIntent` のステータスが 3 分後に `processing` から `requires_payment_method` に遷移します。 | | `generatedSepaDebitIntentsSucceedDisputed@example.com` | `PaymentIntent` のステータスが `processing` から `succeeded` に遷移しますが、不審請求の申し立てがすぐに作成されます。 | | `generatedSepaDebitIntentsFailsDueToInsufficientFunds@example.com` | `PaymentIntent` のステータスが `processing` から `requires_payment_method` に遷移し、`insufficient_funds` のエラーコードが返されます。 | #### PaymentMethod これらの PaymentMethods を使用して `PaymentIntent` のステータスの遷移をテストしてください。これらのトークンは、自動化されたテストで PaymentMethod がサーバー上の SetupIntent にすぐに関連付けられる際に役に立ちます。 | 決済手段 | 説明 | | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `pm_bancontact_generatedSepaDebitIntentsSucceed` | `PaymentIntent` のステータスが `processing` から `succeeded` に遷移します。 | | `pm_bancontact_generatedSepaDebitIntentsSucceedDelayed` | `PaymentIntent` のステータスが 3 分後に `processing` から `succeeded` に遷移します。 | | `pm_bancontact_generatedSepaDebitIntentsFail` | `PaymentIntent` のステータスが `processing` から `requires_payment_method` に遷移します。 | | `pm_bancontact_generatedSepaDebitIntentsFailDelayed` | `PaymentIntent` のステータスが 3 分後に `processing` から `requires_payment_method` に遷移します。 | | `pm_bancontact_generatedSepaDebitIntentsSucceedDisputed` | `PaymentIntent` のステータスが `processing` から `succeeded` に遷移しますが、不審請求の申し立てがすぐに作成されます。 | | `pm_bancontact_generatedSepaDebitIntentsFailsDueToInsufficientFunds` | `PaymentIntent` のステータスが `processing` から `requires_payment_method` に遷移し、`insufficient_funds` のエラーコードが返されます。 |