laravel-stripe-connect

涵盖面向市场平台和多方支付平台的 Stripe Connect（Etsy/Uber/Kickstarter 风格的多方支付，不同于简单的 SaaS 计费——相关内容请参阅 laravel-billing）：账户类型（Standard/Express/Custom）、卖家 KYC 入驻流程、支付流程（直接收款/目标收款、单独收款 + 转账）、平台佣金/申请费、打款、退款与争议/拒付责任，以及合规要求。

Laravel Stripe Connect

Agent 工作流（强制）

在进行任何实现之前，并行启动 3 个 Agent，每个使用一个带有 name 的 Agent 调用：

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
资金流向	客户 → 你	客户 → 卖家（经由你）
账户	1 个 Stripe 账户	平台 + 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

---

参考指南

概念（原因与架构）

主题	参考资料	查阅时机
概述	overview.md	了解 Connect 基础知识
账户类型	account-types.md	选择 Standard/Express/Custom
支付流程	payment-flows.md	直接收款、目标收款与转账之间的选择
入驻流程	onboarding.md	卖家验证流程
费用与佣金	fees-commissions.md	平台收入模式
打款	payouts.md	向卖家付款
退款与争议	refunds-disputes.md	处理拒付
合规	compliance.md	法律与税务要求

模板（完整代码）

模板	使用场景
Seller.php.md	集成 Connect 的卖家模型
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：将 connect/webhook 从 PreventRequestForgery 中排除（参见 [[laravel-auth]]）
• account.updated 处理程序：使用 Context::add('stripe_account', $accountId) 将其传递到队列
• PHP 8.3：对 Seller DTO 和 PayoutResult 使用 final readonly class