laravel-stripe-connect

マーケットプレイスおよびプラットフォーム向けの Stripe Connect を扱います（Etsy/Uber/Kickstarter のような多当事者間決済であり、単純な SaaS 課金とは異なります。後者については laravel-billing を参照してください）。アカウント種別（Standard/Express/Custom）、出品者の KYC オンボーディング、決済フロー（ダイレクトチャージ／デスティネーションチャージ、個別チャージ＋トランスファー）、プラットフォームの手数料／アプリケーションフィー、支払い、返金および紛争／チャージバック責任、ならびにコンプライアンス要件を網羅します。

Laravel Stripe Connect

エージェントワークフロー（必須）

実装を開始する前に、3 つのエージェントを並列で起動してください。それぞれ name を指定した Agent 呼び出しを 1 回ずつ行います。

1. fuse-ai-pilot:explore-codebase - 既存の決済設定、Seller モデルを確認
2. fuse-ai-pilot:research-expert - Context7 経由で最新の Stripe Connect ドキュメントを検証
3. mcp__context7__query-docs - 特定のパターン（アカウント種別、決済フロー）を照会

実装後は、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

Stripe Connect は、プラットフォームおよびマーケットプレイスが支払いを受け取り、出品者やサービス提供者へ支払いを行うことを可能にします。

ユースケース	例	このスキル
マーケットプレイス	Etsy, eBay	✅ はい
オンデマンドサービス	Uber, DoorDash	✅ はい
クラウドファンディング	Kickstarter	✅ はい
支払いを伴う SaaS	Substack, Teachable	✅ はい
シンプルな SaaS	Netflix, Notion	❌ billing を使用

重要な違い: Billing と Connect

項目	Laravel Cashier	Stripe Connect
資金の流れ	顧客 → あなた	顧客 → 出品者（あなた経由）
アカウント	Stripe アカウント 1 つ	プラットフォーム + N 個の出品者アカウント
ユースケース	サブスクリプション	多当事者間決済
複雑さ	シンプル	複雑

---

重要なルール

1. 出品者の本人確認を行う - 支払い前に KYC が必要
2. マイナス残高を処理する - 出品者が返金を賄えない場合、プラットフォームが責任を負う
3. Webhook 駆動 - 決済確認をクライアント側で信頼してはならない
4. アカウント ID を保存する - 常に出品者に stripe_account_id を永続化する
5. テストモードでテストする - 本番環境の前にテストアカウント ID を使用する
6. 責任を理解する - アカウント種別ごとに紛争の費用を誰が負担するかを把握する

---

アーキテクチャ

app/
├── Http/
│   ├── Controllers/
│   │   └── Connect/
│   │       ├── SellerOnboardingController.php
│   │       ├── MarketplacePaymentController.php
│   │       └── PayoutController.php
│   └── Middleware/
│       └── EnsureSellerOnboarded.php
├── Models/
│   ├── Seller.php              ← Connected account holder
│   └── Transaction.php         ← Payment records
├── Listeners/
│   └── ConnectWebhookHandler.php
└── Services/
    └── StripeConnectService.php

config/
└── services.php                ← Stripe keys

routes/
└── web.php                     ← Webhook routes (no CSRF)

---

判断ガイド

どのアカウント種別を使うか？

Who handles customer support?
├── Seller handles everything → Standard
├── Platform handles support → Express or Custom
│   ├── Need full UI control? → Custom
│   └── Want Stripe's dashboard? → Express (recommended)

どの決済フローを使うか？

Who appears on customer's bank statement?
├── Seller's name → Direct charges
├── Platform's name → Destination charges (recommended)
└── Complex split? → Separate charges + transfers

---

主要な概念

概念	説明	参照
コネクテッドアカウント	プラットフォームにリンクされた出品者の Stripe アカウント	account-types.md
オンボーディング	出品者向けの KYC プロセス	onboarding.md
アプリケーションフィー	決済に対するプラットフォームの手数料	fees-commissions.md
デスティネーションチャージ	出品者への自動トランスファーを伴う決済	payment-flows.md
支払い	Stripe 残高から銀行へのトランスファー	payouts.md

---

参照ガイド

概念（WHY とアーキテクチャ）

トピック	参照	参照すべきタイミング
概要	overview.md	Connect の基本を理解するとき
アカウント種別	account-types.md	Standard/Express/Custom を選ぶとき
決済フロー	payment-flows.md	Direct と Destination と Transfers の比較
オンボーディング	onboarding.md	出品者の本人確認プロセス
手数料とコミッション	fees-commissions.md	プラットフォームの収益モデル
支払い	payouts.md	出品者への支払い
返金と紛争	refunds-disputes.md	チャージバックの処理
コンプライアンス	compliance.md	法務および税務要件

テンプレート (完全なコード)

テンプレート	使用する場面
Seller.php.md	Connect 統合を備えた Seller モデル
SellerOnboardingController.php.md	OAuth とオンボーディングのフロー
MarketplacePaymentController.php.md	手数料付きのチャージの作成
PayoutController.php.md	出品者の支払いの管理
ConnectWebhookHandler.php.md	Webhook イベントの処理
ConnectRoutes.php.md	ルート定義

---

クイックリファレンス

コネクテッドアカウントの作成

$account = \Stripe\Account::create([
    'type' => 'express',
    'country' => 'FR',
    'email' => $seller->email,
    'capabilities' => [
        'card_payments' => ['requested' => true],
        'transfers' => ['requested' => true],
    ],
]);

$seller->update(['stripe_account_id' => $account->id]);

オンボーディングリンクの作成

$link = \Stripe\AccountLink::create([
    'account' => $seller->stripe_account_id,
    'refresh_url' => route('connect.onboarding.refresh'),
    'return_url' => route('connect.onboarding.complete'),
    'type' => 'account_onboarding',
]);

return redirect($link->url);

手数料付きのデスティネーションチャージ

$payment = \Stripe\PaymentIntent::create([
    'amount' => 10000, // €100.00
    'currency' => 'eur',
    'payment_method' => $paymentMethodId,
    'confirm' => true,
    'application_fee_amount' => 1500, // €15.00 platform fee
    'transfer_data' => [
        'destination' => $seller->stripe_account_id,
    ],
]);

アカウントステータスの確認

$account = \Stripe\Account::retrieve($seller->stripe_account_id);

$isOnboarded = $account->charges_enabled && $account->payouts_enabled;
$needsInfo = !empty($account->requirements->currently_due);

---

ベストプラクティス

推奨

• ほとんどのマーケットプレイスでは Express アカウントを使用する
• すべての Connect イベントに対して Webhook ハンドラーを実装する
• 取引記録をローカルに保存する
• account.updated を処理してオンボーディングステータスを追跡する
• 支払い作成には冪等性キーを使用する
• Stripe CLI とテストクロックでテストする

非推奨

• KYC 完了前に支払いを有効にする
• マイナス残高のシナリオを無視する
• Webhook 署名の検証を省略する
• Stripe アカウント ID をハードコードする
• 紛争通知の処理を忘れる
• 出品者の残高を確認せずに返金を処理する

---

Laravel 13 に関する注意事項

Stripe Connect (stripe/stripe-php 21.x、現在は 21.3) は Laravel 13 互換です。ここで使用されている静的メソッド (\Stripe\Account::create()、AccountLink::create()) は今も存在します。調整点:

• Connect Webhook: PreventRequestForgery から connect/webhook を除外します ([[laravel-auth]] を参照)
• account.updated ハンドラー: Context::add('stripe_account', $accountId) を使用してキューに伝播させます
• PHP 8.3: Seller DTO と PayoutResult に final readonly class を使用します