この記事の目的

Stripe を学び始めたのですが、PaymentIntent / SetupIntent / Customer / PaymentMethod / Account など多くのオブジェクトが登場し、すぐには全体の見通しを立てるのが難しいと感じました。

Stripe の実装に慣れれば自然に扱えるとは思いつつも、最初にこれらの関係性を整理しておくことが結果的に学習の近道になると考えました。

Stripe のドキュメントは日本語でとても読みやすいのですが、個別の API 仕様を読む前に、まずは 「誰が支払い、誰が受け取り、何を管理しているのか」という登場人物の相関図を先に掴んでおくと、その後の理解がスムーズになると感じました。

本記事はそんな自身の学習メモを整理したものです。

Stripeの支払い構造を 3 階層で理解する

層	担当	代表オブジェクト	役割
①取引層	お金のやり取り	`PaymentIntent`, `SetupIntent`, `Charge`, `Refund`	支払い・返金のフロー（状態）を管理
②主体層	誰が払う／受け取る	`Customer`, `Account`, `Consumer`	支払いの当事者を管理（顧客／加盟店）
③補助層	決済手段	`PaymentMethod`（`card` など）	多様な支払い手段を統一的に扱う

本記事は全体の俯瞰が目的のため、詳細な状態遷移・例外ケースはまた別の記事で整理しようと思います。

Stripe では、「今回の支払い」も「将来に向けた支払い手段の保存」もIntent（意図）として扱います。

今回の支払いを状態として管理（例：要支払い手段 → 認証要 → 成功）

将来の支払いに備えて支払い手段（PaymentMethod）を保存。ここでは課金は発生しない。

SetupIntent は将来の支払いのために PaymentMethod を Customer に紐付けるためのオブジェクト

PaymentIntent が成功した結果として作成される実際の課金記録（レシートのようなもの）

Charge に対する返金トランザクション

立場	オブジェクト	説明
支払う人	`Customer`	自社サービス上の顧客に対応複数の `PaymentMethod` を保持・再利用できる。
受け取る人	`Account`	Stripe Connect 利用時の加盟店・出店者資金の受け取り主体
Stripe側の共通顧客ID	`Consumer`	Stripe Link 等で使われるグローバルID

Stripe の Customer は自社のDB等で管理するユーザーとは別概念。PCI DSS 準拠で安全に支払い手段を扱うための抽象IDの位置づけ

カード（card）、口座振替（jp_bank_account など）、Apple Pay／Google Pay など、多様な決済手段を PaymentMethod で統一的に扱えます。
開発者は「どの手段を選んだか」に集中できるので、これを用いることで実装がシンプルになります。

マーケットプレイス型では、「支払う人（Customer）」と「受け取る人（Account）」が分かれます。PaymentIntent を基点に、プラットフォーム手数料や売上の送金を制御します。

Connect を使わない一般的な EC では Account を意識せずに進められます。

関係の向きと必須／任意を最小限で表現したクラス図です。
（実装の全ケースを網羅しない簡略図）

※Account は Connect 利用時のみ登場するため点線の任意関連にしている

※ Multi-capture(Charge と PaymentIntent が 1:多になり得る）や Refund の多様な作成パスなどの詳細は省略。

Stripeに登場する多くのオブジェクトは一見すると複雑に見えますが、本記事で紹介した「①取引層」「②主体層」「③補助層」という3つの階層で役割を整理することでその関係性がクリアになりそうな気がしました。

特に重要なポイントは以下の通りです。

取引の中心は常に Intent であること
- 「今回の支払い」なら PaymentIntent
- 「将来のためのカード登録」なら SetupIntent
登場人物（主体）を明確にすること
- お金を払うのは Customer
- その支払い手段は PaymentMethod
- （Connect利用時に）お金を受け取るのが Account

このシンプルなメンタルモデルを頭に入れておけば、公式ドキュメントを読んだり実際のコードを書いたりする際の理解度が向上するかもしれないです！