# Stripe API の概要

Stripe API オブジェクトがどのように連携するか、またその組み合わせのベストプラクティスについてご紹介します。

Connect プラットフォームが [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) を使用している場合は、Stripe の [ガイド](https://docs.stripe.com/connect/use-accounts-as-customers.md)をご確認の上、コード内の `Customer` およびイベント参照を同等の Accounts v2 API リファレンスに置き換えてください。

Stripe API は、使い方がわかると、強力で柔軟なツールとなります。この API の説明では、API の理解を深めるために重要な情報をご紹介します。

- API 全体で使用される中心となる概念
- 成功する支払いの道筋
- 役割を果たすオブジェクトと、それらが必要な場合の特定方法
- これらのオブジェクトを組み合わせて使用するための共通パターンとベストプラクティス

これらのパターンを理解すると、Stripe のチュートリアルにある事前に作成されたコードを超える機能を実現できます。以前の組み込みを移行して、最新のパターンを使用し、シンプルなパターンを新しい方法で組み合わせ、さらに将来の成長に向けて計画を立てることができます。

## 中心となる概念

### すべてがオブジェクト

API を使用して作成したかに関わらず、Stripe アカウントのすべての要素はオブジェクトです。たとえば、残高は [Balance (残高](https://docs.stripe.com/api/balance.md)) オブジェクトに対応し、顧客は [Subscription](https://docs.stripe.com/api/subscriptions.md) (サブスクリプション) オブジェクトで追跡され、支払いの詳細は [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) (支払い方法) オブジェクトに保存されます。

ローコードまたはノーコードの組み込みでも、これらのオブジェクトは生成されます。ダッシュボードで実行したアクションについても同様です。たとえば、ダッシュボードで商品を手動で作成した場合でも、[Product](https://docs.stripe.com/api/products.md) オブジェクトが作成されます。

### オブジェクトはリアルタイムで変化する

Stripe の組み込みは複雑なプロセスに対応します。

API は 1 つのオブジェクトを使用して各プロセスを追跡します。プロセスの開始時にオブジェクトを作成し、それぞれのステップの後で `status` を参照して、次に実行する必要のある操作を確認できます。これは「ステートマシン」と呼ばれることがあります。

たとえば、決済の完了時に顧客が複数の支払い方法を試す場合があります。1 つの支払い方法が失敗すると、`requires_payment_method` の `status` が、顧客に別の支払い方法をリクエストするようお客様に知らせます。

### 組み込みは連携オブジェクトで構成される

決済を受け付けるために、システムは複数のコアオブジェクトを作成し、複数の状態を使用してコアオブジェクトを管理する必要があります。

Stripe の組み込みは、Stripe とやり取りしてこのような作成と管理を処理するシステムです。

実装によっては、顧客の追跡、サブスクリプションの管理など、さらに多くの機能を実行します。それでも、中心となる決済機能は同じオブジェクトとステップから提供され、そのコアの周りにさらにオブジェクトが追加されます。

## 決済オブジェクト

Stripe は、決済を円滑化するためにさまざまな関連オブジェクトを使用します。特定のニーズに合った実装を構築する前に、これらのオブジェクトがどのように連携するかを理解しておく必要があります。

決済オブジェクトの役割と機能の概要を説明しているこのビデオをご覧ください。
[Watch on YouTube](https://www.youtube.com/watch?v=CUAY6IQcVQM)
Stripe の決済の導入オプションの詳細については、以下のガイドをご覧ください。

- [Payment Links](https://docs.stripe.com/payment-links.md)
- [Checkout](https://docs.stripe.com/payments/checkout.md)
- [Subscriptions](https://docs.stripe.com/billing.md)
- [Invoicing](https://docs.stripe.com/invoicing.md)
- [Payment Intents](https://docs.stripe.com/payments/payment-intents.md)

## 支払いの道筋

最新の Stripe の導入では、決済ごとに [PaymentIntent (支払いインテント)](https://docs.stripe.com/api/payment_intents.md) と呼ばれるオブジェクトが使用されます。名前のとおり、このオブジェクトは支払いを回収するお客様の「意図」を示し、これを実行する過程の各ステップを追跡します。

たとえば、顧客がカートに 100 USD の商品を入れて**購入**ボタンをクリックするとします。まだ顧客の購入前であり、購入されない可能性もあります (ある時点で顧客が決済フローを中断したり、カード発行会社が支払いを拒否する場合など)。それでも、**購入**をクリックすることで顧客の購入する「意図」が示され、お客様にはこれをサポートする意思があります。この時点で、組み込みは金額が 100 USD の `PaymentIntent` オブジェクトを作成し、残りのプロセスを追跡します。

成功する `PaymentIntent` の道筋は[いくつかのステータス](https://docs.stripe.com/payments/paymentintents/lifecycle.md)を遷移します。これを簡略化した図を次に示します。
requires_payment_method から requires_confirmation に変化した後、processing に移行して、succeeded または canceled のいずれかのステータスで終了する PaymentIntent のステータスを示します (See full diagram at https://docs.stripe.com/payments-api/tour)
### 決済手段

PaymentIntent は `requires_payment_method` のステータスで開始します。Stripe ではこれを先に進めるため、顧客の支払い方法に関する詳細 (カード番号または他の決済システムの認証情報) が必要になります。

実装は [PaymentMethod (支払い方法)](https://docs.stripe.com/api/payment_methods.md) と呼ばれる API オブジェクトを使用して、このような詳細情報を表します。一部の実装では、このオブジェクトを作成して PaymentIntent に関連付けるコードをお客様が記述します。それ以外では、Stripe が詳細を収集してこの操作を行います。[Setup Intents API を使用](https://docs.stripe.com/payments/setup-intents.md)して、今後の PaymentIntents で使用する支払い方法を作成し、保存することもできます。

### 確定

次のステータスは `requires_confirmation` です。インタラクティブな決済フローでは、顧客は支払いを行う意思と、指定した手段でそれを実行する意思を確定する必要があります。1 回限りのオンライン決済では、通常**支払う**ボタンをクリックしたときに確定します。

顧客が**支払う**をクリックするか、インテントを確定すると、API コールで Stripe に通知が届きます。実装によっては、このコールを実行するコードをお客様が作成します。Stripe は [Stripe Elements](https://docs.stripe.com/payments/elements.md) という埋め込み可能な UI エレメントを用意しています。これを利用すると、コードを作成できるようになるとともに、カスタムの実装を構築する柔軟性も提供されます。[Stripe Checkout](https://docs.stripe.com/payments/checkout.md) や [Payment Links](https://docs.stripe.com/payment-links.md) といったその他の実装では、Stripe がコールを実行して、後続のステップを処理します。Stripe を導入し、さまざまなオブジェクトを組み合わせて実際のユースケースに対応するための方法が多数用意されています。[オンライン決済向けの導入オプションの詳細をご確認ください。](https://docs.stripe.com/payments/online-payments.md)

ほとんどの場合、PaymentIntent が確定されると、資金を移動するという特定の試行を表す [Charge (支払い)](https://docs.stripe.com/api/charges.md) が作成されきます。Charge は成功または失敗します。失敗した場合、通常は新しい支払いの詳細を指定して PaymentIntent を再度確定すると、支払いを再試行できます。PaymentIntent を新たに作成せずに試行を直ちに実行することを許可すると、購入完了率が上がる傾向にあります。

### 処理中および成功

インテントの状態は `processing` になり、Stripe はこの時点で決済の処理を試みます。

この処理はいつでも Stripe によって実行され、複数のステップに分かれる場合があります (クレジットカードの場合、これらのステップは[カードの仕組み](https://docs.stripe.com/payments/cards/overview.md)に含まれています)。ステップが実行されると、インテントの状態が結果で更新され、`succeeded` になるか、失敗した場合は `requires_payment_method` に戻ります。

処理が終わると、最後のオブジェクトである [Event (イベント)](https://docs.stripe.com/api/events.md) を使用します。`Event` オブジェクトを使用することでアクティビティが表示されます。このとき、アクティビティは「支払いが成功しました」または「支払いが失敗しました」と表示されます。一部のシステムでは、[Webhook エンドポイント](https://docs.stripe.com/webhooks.md)を使用してイベントに応答するカスタムコードを記述することになります。[Checkout](https://docs.stripe.com/payments/checkout.md) や [Payment Links](https://docs.stripe.com/payment-links.md) などを連携する場合、Stripe がイベントをリッスンし、事前に用意したレスポンスで返します。