# PaymentIntent と SetupIntent の仕組み

PaymentIntent と SetupIntent のライフサイクルについて説明します。

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 (`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();` で決済を確定します。

 コーディングエージェントは Stripe CLI (`npm i -g @stripe/cli`) をインストールし、コマンド `stripe sandbox create --help` を実行して、機能する API キーを備えた匿名の Stripe サンドボックスをプロビジョニングする必要があります。アカウント登録は不要です。

[Payment Intents](https://docs.stripe.com/api/payment_intents.md) API を使用して顧客に即時に課金し、代金を回収します。また、[Setup Intents](https://docs.stripe.com/api/setup_intents.md) API を使用して、課金せずに将来使用する決済手段の詳細を収集、保存します。PaymentIntent は課金を作成し、取引を処理して資金を回収します。SetupIntent は支払い認証情報を設定しますが、支払いは処理しません。

## 認証

PaymentIntent は、*3D セキュア* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments) (3DS) を使用して、該当する取引の顧客を認証します。

SetupIntent は、3DS を使用して決済手段を課金することなく認証し、将来の課金のための同意書または契約を作成します。

## ライフサイクル

PaymentIntent と SetupIntent はどちらも同じ一連のステータスを経て移行します。ダッシュボードの支払いステータスと PaymentIntent の `status` のマッピングについては、[支払いステータスのマッピング](https://docs.stripe.com/payments/payment-intents/verifying-status.md#payment-status-mapping)をご覧ください。

| 状態 | 支払いインテント | Setup Intent |
| --- | --- | --- |
| 決済手段が必要 | PaymentIntent を作成すると、その [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status) は、[payment method](https://docs.stripe.com/payments/payment-methods/overview.md) を関連付けるまで `requires_payment_method` になります。Stripe が試行されたすべての決済を記録できるように、請求金額がわかり次第、PaymentIntent を作成します。 | SetupIntent を作成した後、決済手段を関連付けるまで、その [status](https://docs.stripe.com/api/setup_intents/object.md#setup_intent_object-status) は `requires_payment_method` になります。 |
| 確定が必要 | 顧客が決済情報を提供すると、PaymentIntent は `requires_confirmation` ステータスになり、確定できる状態になります。ほとんどの連携では、決済が確定される際に決済手段情報が送信されるため、この状態はスキップされます。 | 顧客が支払い情報を提供すると、SetupIntent は `requires_confirmation` ステータスになり、確定の準備が整います。大半の実装では、SetupIntent の確定時に決済手段の情報が送信されるため、この状態はスキップされます。 |
| 要対応
> \#### API の変更点
> 
> [2019-02-11](https://docs.stripe.com/upgrades.md#2019-02-11) 以前の API のバージョンでは、`requires_payment_method` の代わりに `requires_source`、`requires_action` の代わりに `requires_source_action` が表示されます。 | [3D セキュア](https://docs.stripe.com/payments/3d-secure.md)での認証など、決済に追加アクションが必要な場合、PaymentIntent のステータスは `requires_action` になります。 | 3D セキュアでの認証など、設定に追加アクションが必要な場合、SetupIntent のステータスは `requires_action` になります。 |
| 処理中 | 必要なアクションが処理された後、支払いに口座振替などの *非同期型の決済手段* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed) が使用された場合に発生します。これらのタイプの決済手段では、処理に数日かかることがあります。資金のオーソリと確定を個別に[実行している](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md)場合、PaymentIntent は代わりに `requires_capture` に移行することがあります。その場合、資金を確定しようとすると、決済手段に応じて `processing` または `succeeded` に移行します。 | 必要なアクションが処理された後に発生します。一部の決済手段 (カードなど) は迅速に処理されますが、他の決済手段では処理に数日かかる場合があります。 |
| 成功 | PaymentIntent のステータスが `succeeded` の場合、対応する決済フローが完了したことを意味します。資金はアカウントにあり、注文に確実に対応できます。顧客に返金する必要がある場合は、[Refunds](https://docs.stripe.com/api/refunds.md) API を使用できます。支払い試行が失敗した場合 (拒否された場合など)、支払いを再試行できるように PaymentIntent のステータスは `requires_payment_method` に戻ります。 | SetupIntent のステータスが `succeeded` の場合、設定が成功したことを意味します。この決済手段を Customer オブジェクトに関連付けて、その決済手段を将来の支払いに使用できるようになります。設定が失敗した場合、SetupIntent のステータスは `requires_payment_method` に戻ります。 |
| キャンセル済み | PaymentIntent は、`processing` または `succeeded` 状態になる前にキャンセルできます。キャンセルすると、その PaymentIntent は今後の支払い試行に対して無効になり、保留中の資金が解放されます。この操作は元に戻せません。また、決済手段が [ACH](https://docs.stripe.com/payments/ach-direct-debit.md)、[ACSS](https://docs.stripe.com/payments/acss-debit.md)、[AU BECS](https://docs.stripe.com/payments/au-becs-debit.md)、[BACS](https://docs.stripe.com/payments/payment-methods/bacs-debit.md)、[NZ BECS](https://docs.stripe.com/payments/nz-bank-account.md)、または [SEPA](https://docs.stripe.com/payments/sepa-debit.md) の場合、`processing` 状態の PaymentIntent もキャンセルできます。ただし、キャンセルの時間枠は限られており変動するため、キャンセルが失敗する場合があります。また、PaymentIntent が複数回 [confirmed](https://docs.stripe.com/api/payment_intents/confirm.md) されると、自動的に `canceled` に移行する場合があります。 | SetupIntent は、`processing` または `succeeded` 状態になる前にキャンセルできます。キャンセルすると、その SetupIntent は今後の設定試行に対して無効になります。この操作は元に戻せません。 |