laravel-stripe-connect

用途

laravel-stripe-connect 是一个 Laravel 方向的智能体技能，适用于在项目中实现多商户市场支付、卖家入驻、平台佣金、提现或分账等场景，底层对接 Stripe Connect。资料列出的典型用例包括市场平台（如 Etsy、eBay 类）、按需服务（如 Uber、DoorDash 类）、众筹（如 Kickstarter 类）以及带付款分发的 SaaS（如 Substack、Teachable 类）；普通订阅型 SaaS 应使用 Billing 而非 Connect。

主要能力

技能本身不提供运行时代码库，而是以“概念参考 + 完整代码模板 + 工作流约束”的方式辅助开发：

概念文档：Connect 概览、账户类型（Standard/Express/Custom）、支付流程（Direct/Destination/Transfers）、入驻与 KYC、费用与佣金、提现、退款与争议、合规。
代码模板：Seller 模型、SellerOnboardingController、MarketplacePaymentController、PayoutController、ConnectWebhookHandler、ConnectRoutes。
决策指引：根据谁负责客服、是否需要完全控制界面等条件选择账户类型；根据客户银行账单上显示的名称选择支付流程（推荐 Destination charges）。
快速参考片段：创建 Express 账户、创建 onboarding 链接、创建带 application fee 的 Destination 扣款、检查账户状态。
最佳实践与禁止事项清单。
Laravel 13 与 stripe/stripe-php 21.x 的兼容性说明。

使用方式

资料规定了一套强制工作流：任何实现开始前，并行启动三个代理——explore-codebase 检查现有支付设置与 Seller 模型；research-expert 通过 Context7 核对最新 Stripe Connect 文档；mcp__context7__query-docs 查询账户类型、支付流程等具体模式。实现完成后运行 sniper 进行验证。随后按需查阅概念文档与模板进行开发。

快速参考中的关键调用包括：

$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);

架构与规则

建议的目录结构包含 Controllers/Connect（入驻、市场支付、提现）、EnsureSellerOnboarded 中间件、Seller 与 Transaction 模型、ConnectWebhookHandler 监听器、StripeConnectService 服务，以及 config/services.php 中的密钥和 web.php 中免 CSRF 的 webhook 路由。

关键规则：提现前必须完成卖家身份验证（KYC）；需处理负余额（卖家无法承担退款时平台担责）；支付确认必须以 webhook 为准，不能信任客户端；Seller 上必须持久化 stripe_account_id；先用测试模式与测试账户；需理解不同账户类型下争议责任归属。

最佳实践

推荐：大多数市场使用 Express 账户；为所有 Connect 事件实现 webhook 处理；在本地保存交易记录；用 account.updated 跟踪入驻状态；支付创建使用幂等键；用 Stripe CLI 和 test clocks 测试。

避免：KYC 未完成即启用提现；忽略负余额场景；跳过 webhook 签名验证；硬编码 Stripe 账户 ID；忘记处理争议通知；未检查卖家余额就处理退款。

限制

资料未提供该技能的收费、价格、平台支持范围或实际效果信息；技能不包含可直接运行的完整实现，模板内容需结合项目实际情况调整。资料提及的 Laravel 兼容性基于 stripe/stripe-php 21.x（当前 21.3）。

技能介绍

用途

主要能力

使用方式

架构与规则

最佳实践

限制