# Payment Intents API

Stripe の支払いに Payment Intents API を使用する方法をご紹介します。

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

[PaymentIntent (支払いインテント)](https://docs.stripe.com/api/payment_intents.md) API を使用して、[PaymentIntent のライフサイクル](https://docs.stripe.com/payments/paymentintents/lifecycle.md)を通じてステータスが変化する複雑な決済フローを処理できるシステムを構築します。この API は、支払いの作成から決済までを追跡し、必要に応じて追加の認証ステップをトリガーします。

[Payment Intents](https://docs.stripe.com/api/payment_intents.md) API を使用すると、以下のようなメリットがあります。

- 自動認証処理
- 二重支払いの防止
- [べき等キー](https://docs.stripe.com/api/idempotent_requests.md)の問題がない
- *強力な顧客認証* (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) (SCA) および同様の規制変更への対応

## 包括的な API セット

[Payment Intents](https://docs.stripe.com/api/payment_intents.md) API、[Setup Intents](https://docs.stripe.com/api/setup_intents.md) API、[Payment Methods](https://docs.stripe.com/api/payment_methods.md) API を組み合わせて使用します。上記の API は、動的な支払い (*3D セキュア* (3D Secure (3DS) provides an additional layer of authentication for credit card transactions that protects businesses from liability for fraudulent card payments)などの追加認証) への対応に役立ち、また他の国々にビジネスを拡大する準備となります。さらに、新しい規制や地域固有の決済手段に対応することもできます。

Payment Intents API を利用した組み込みを構築するには、2 つのアクションが必要です。それは PaymentIntent の作成と*確定* (Confirming a PaymentIntent indicates that the customer intends to pay with the current or provided payment method. Upon confirmation, the PaymentIntent attempts to initiate a payment)です。一般的に各 PaymentIntent はアプリケーションの 1 つのショッピングカートや顧客セッションと関連付けられています。PaymentIntent はサポートされる支払い方法、回収金額、指定通貨といった取引の詳細をカプセル化します。

## PaymentIntent を作成する

使用を開始するには、[決済の受け付けガイド](https://docs.stripe.com/payments/accept-a-payment.md?ui=elements)をご覧ください。このガイドは、サーバーで PaymentIntent を作成し、PaymentIntent オブジェクト全体を渡す代わりに、その *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) をクライアントに渡す方法を説明します。

[PaymentIntent を作成](https://docs.stripe.com/api/payment_intents/create.md)する際には、金額や通貨などのオプションを指定できます。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd
```

### ベストプラクティス

- PaymentIntent は、金額がわかり次第 (顧客が決済プロセスを開始したときなど) 作成することをお勧めします。これは[購買ファネル](https://en.wikipedia.org/wiki/Purchase_funnel)の追跡に役立ちます。金額が変更された場合は、その [amount](https://docs.stripe.com/api.md#payment_intent_object-amount) を [update](https://docs.stripe.com/api.md#update_payment_intent) できます。たとえば、顧客が決済プロセスを離れてカートに新しいアイテムを追加した場合は、顧客が再度決済プロセスを開始するときに金額を更新する必要があります。

- 購入プロセスを中断し、後で再開する場合は、新しい PaymentIntent を作成するのではなく、同じ PaymentIntent の再利用を試してください。各 PaymentIntent には固有の ID があり、再度必要になった際はその ID を使用して[取得](https://docs.stripe.com/api.md#retrieve_payment_intent)できます。アプリケーションのデータモデルでは、PaymentIntent の ID を顧客のショッピングカートやセッションに保存することで、簡単に取得できます。PaymentIntent を再利用するメリットは、[オブジェクトのステータス](https://docs.stripe.com/payments/paymentintents/lifecycle.md)によって特定のカートやセッションの失敗した支払いを追跡できることです。

- 同じ購入に対して PaymentIntent を重複して作成するのを防止するために、[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を必ず指定してください。このキーは通常、アプリケーションのカートまたは顧客セッションに関連付けられる ID に基づいています。

## クライアント側に client secret を渡す

PaymentIntent には、[client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret)、すなわち個々の PaymentIntent に固有のキーが格納されます。アプリケーションのクライアント側で、支払いを完了するために関数 ([stripe.confirmCardPayment](https://docs.stripe.com/js.md#stripe-confirm-card-payment) や [stripe.handleCardAction](https://docs.stripe.com/js.md#stripe-handle-card-action) など) を呼び出す際に、Stripe.js は client secret をパラメーターとして使用します。

### client secret を取得する

PaymentIntent には、*client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。

#### 1 ページのアプリケーション

ブラウザーの `fetch` 関数を使用して、サーバーのエンドポイントから client secret を取得します。この方法は、クライアント側が 1 ページのアプリケーションで、特に React などの最新のフロントエンドフレームワークで構築されている場合に最適です。client secret を処理するサーバーのエンドポイントを作成します。

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

その後、クライアント側で JavaScript を使用して client secret を取得します。

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### サーバ側のレンダリング

サーバーからクライアントに client secret を渡します。この方法は、アプリケーションがブラウザーへの送信前に静的なコンテンツをサーバーで生成する場合に最適です。

決済フォームに [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) を追加します。サーバー側のコードで、PaymentIntent から client secret を取得します。

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

> client secret を使用して、PaymentIntent で指定した金額の支払いプロセスを完了できます。client secret は、記録したり、URL に埋め込んだり、顧客以外の人に公開することがないようにしてください。client secret が含まれるすべてのページで *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) を設定するのを忘れないでください。

## 支払い後

クライアントが決済を確定したら、ベストプラクティスとして、決済が成功したか失敗したかを検出するために、サーバーで [Webhook を監視](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks)することをお勧めします。

支払いが複数回行われた場合、`PaymentIntent` には複数の [Charge](https://docs.stripe.com/api/charges.md) オブジェクトが関連付けられていることがあります。たとえば、再試行によって複数の `Charges` を作成できます。支払いごとに、[結果](https://docs.stripe.com/api/charges/object.md#charge_object-outcome)と[使用された支払い方法](https://docs.stripe.com/api/charges/object.md#charge_object-payment_method_details)の詳細を調べることができます。

## 今後の支払いのために支払い方法を最適化する

[setup_future_usage](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-setup_future_usage) パラメーターは、将来の再使用に備えて支払い方法を保存します。カードの場合、このパラメーターは [SCA](https://docs.stripe.com/strong-customer-authentication.md) などの地域の法規制やネットワーク規則に準拠してオーソリ率を最適化します。この支払い方法を将来どのように使用するかを考慮して、使用する値を決定します。

| 支払い方法の使用計画                                                                                                                                                          | 使用する setup_future_usage 列挙型値 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| *オンセッション* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)支払いのみ | `on_session`                 |
| *オフセッション* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)支払いのみ | `off_session`                |
| オンセッション支払いとオフセッション支払いの両方                                                                                                                                            | `off_session`                |

オンセッション支払い用に設定されたカードによる*オフセッション* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information)支払いを受け入れることはできますが、銀行がオフセッション支払いを拒否し、カード保有者の認証を求める可能性が高くなります。

次の例は、PaymentIntent を作成し、`setup_future_usage` を指定する方法を示しています。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session
```

> オフセッション支払い用の設定では負担が増える可能性が高くなります。保存したカードでオフセッション支払いを受け付けない場合は、*オンセッション* (A payment is described as on-session if it occurs while the customer is actively in your checkout flow and able to authenticate the payment method)の設定を使用してください。

## 動的な明細書表記

By default, your Stripe account’s [statement descriptor](https://docs.stripe.com/get-started/account/set-up.md#public-business-information) appears on customer statements whenever you charge their card. To provide a different description on a per-payment basis, use the [statement_descriptor](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-statement_descriptor) parameter.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "statement_descriptor_suffix=Custom descriptor"
```

> #### メモ
> 
> カード以外の決済には `statement_descriptor` パラメータを使用し、カードの決済には `statement_descriptor_suffix` を使用します。

[明細書表記](https://docs.stripe.com/get-started/account/statement-descriptors.md)は最大 22 文字で、特殊文字 `<`, `>`、`'`、`"`、および `*` は使用できません。また、数字だけにすることもできません。動的な明細書表記を使用するときは、Stripe ダッシュボードで設定された[明細書表記プレフィックス](https://dashboard.stripe.com/settings/public)に動的なテキストが付加されます。デフォルトの明細書表記と動的な部分を分離するため、アスタリスク (`*`) と空のスペースも追加されます。これらの 2 文字も 22 文字の上限に含まれます。

## メタデータに情報を保存する

Stripe では、支払い処理などの最も一般的なリクエストへの[メタデータ](https://docs.stripe.com/api.md#metadata)の追加がサポートされています。メタデータは顧客には表示されず、また不正防止システムでの支払いの拒否やブロックでは考慮されません。

メタデータを使用すると、自社に有用な関連情報を Stripe アクティビティーに関連付けることができます。

追加したメタデータはすべてダッシュボードで確認でき (個々の支払いのページを表示するときなど)、一般的なレポートで使用することもできます。一例として、お客様のストアの注文 ID を、その注文の PaymentIntent に関連付けることができます。このようにすると、Stripe での支払いを自社システム内の注文と簡単に照合できるようになります。

*Radar for Teams* (Radar for Fraud Teams helps you fine-tune how Radar operates, get fraud insights on suspicious charges, and assess your fraud management performance from a unified dashboard) を使用している場合は、追加の顧客情報や注文情報をメタデータとして渡すことを検討してください。そうすることで、[メタデータ属性を用いた Radar ルールを作成](https://docs.stripe.com/radar/rules/reference.md#metadata-attributes)でき、ダッシュボード内でより多くの情報を確認できるようになるため、審査プロセスを迅速化できます。

PaymentIntent が支払いを作成する際、PaymentIntent はそのメタデータを支払いにコピーします。その後の PaymentIntent によるメタデータの更新では、以前作成された支払いのメタデータは変更されません。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]=card" \
  -d "metadata[order_id]=6735"
```

> 機密情報 (個人が特定される情報、カード詳細など) は、メタデータや、PaymentIntent の `description` パラメーターに保存しないでください。

## See also

- [オンラインで決済を受け付ける](https://docs.stripe.com/payments/accept-a-payment.md?platform=web)
- [iOS アプリで決済を受け付ける](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=ios)
- [Android アプリで決済を受け付ける](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=mobile&platform=android)
- [支払いの事前設定](https://docs.stripe.com/payments/save-and-reuse.md)