---
name: laravel-stripe-connect
description: Use when implementing multi-vendor marketplace payments, seller onboarding, commissions, payouts, or split payments with Stripe Connect.
versions:
  laravel: "13.0"
  stripe-php: "21.x"
  php: "8.3"
user-invocable: true
references: references/overview.md, references/account-types.md, references/payment-flows.md, references/onboarding.md, references/fees-commissions.md, references/payouts.md, references/refunds-disputes.md, references/compliance.md, references/templates/Seller.php.md, references/templates/SellerOnboardingController.php.md, references/templates/MarketplacePaymentController.php.md, references/templates/PayoutController.php.md, references/templates/ConnectWebhookHandler.php.md, references/templates/ConnectRoutes.php.md
related-skills: laravel-billing, laravel-api, laravel-auth
---

<objective>
Covers Stripe Connect for marketplaces and platforms (Etsy/Uber/Kickstarter-
style multi-party payments, as opposed to simple SaaS billing — see
laravel-billing for that): account types (Standard/Express/Custom), seller
KYC onboarding, payment flows (direct/destination charges, separate charges
+ transfers), platform commission/application fees, payouts, refunds and
disputes/chargeback liability, and compliance requirements.
</objective>

# Laravel Stripe Connect

## Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Check existing payment setup, Seller model
2. **fuse-ai-pilot:research-expert** - Verify latest Stripe Connect docs via Context7
3. **mcp__context7__query-docs** - Query specific patterns (account types, payment flows)

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

## Overview

Stripe Connect enables platforms and marketplaces to accept payments and pay out sellers/service providers.

| Use Case | Example | This Skill |
|----------|---------|------------|
| **Marketplace** | Etsy, eBay | ✅ Yes |
| **On-demand services** | Uber, DoorDash | ✅ Yes |
| **Crowdfunding** | Kickstarter | ✅ Yes |
| **SaaS with payouts** | Substack, Teachable | ✅ Yes |
| **Simple SaaS** | Netflix, Notion | ❌ Use billing |

### Key Difference: Billing vs Connect

| Aspect | **Laravel Cashier** | **Stripe Connect** |
|--------|--------------------|--------------------|
| **Money flow** | Customer → You | Customer → Seller (via you) |
| **Accounts** | 1 Stripe account | Platform + N seller accounts |
| **Use case** | Subscriptions | Multi-party payments |
| **Complexity** | Simple | Complex |

---

## Critical Rules

1. **Verify seller identity** - KYC required before payouts
2. **Handle negative balances** - Platform liable if seller can't cover refunds
3. **Webhook-driven** - Never trust client-side for payment confirmation
4. **Store account IDs** - Always persist `stripe_account_id` on sellers
5. **Test with test mode** - Use test account IDs before production
6. **Understand liability** - Know who pays for disputes per account type

---

## Architecture

```
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)
```

---

## Decision Guide

### Which Account Type?

```
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)
```

### Which Payment Flow?

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

---

## Key Concepts

| Concept | Description | Reference |
|---------|-------------|-----------|
| **Connected Account** | Seller's Stripe account linked to platform | [account-types.md](references/account-types.md) |
| **Onboarding** | KYC process for sellers | [onboarding.md](references/onboarding.md) |
| **Application Fee** | Platform's commission on payments | [fees-commissions.md](references/fees-commissions.md) |
| **Destination Charge** | Payment with automatic transfer to seller | [payment-flows.md](references/payment-flows.md) |
| **Payout** | Transfer from Stripe balance to bank | [payouts.md](references/payouts.md) |

---

## Reference Guide

### Concepts (WHY & Architecture)

| Topic | Reference | When to Consult |
|-------|-----------|-----------------|
| **Overview** | [overview.md](references/overview.md) | Understanding Connect fundamentals |
| **Account Types** | [account-types.md](references/account-types.md) | Choosing Standard/Express/Custom |
| **Payment Flows** | [payment-flows.md](references/payment-flows.md) | Direct vs Destination vs Transfers |
| **Onboarding** | [onboarding.md](references/onboarding.md) | Seller verification process |
| **Fees & Commissions** | [fees-commissions.md](references/fees-commissions.md) | Platform revenue model |
| **Payouts** | [payouts.md](references/payouts.md) | Paying sellers |
| **Refunds & Disputes** | [refunds-disputes.md](references/refunds-disputes.md) | Handling chargebacks |
| **Compliance** | [compliance.md](references/compliance.md) | Legal and tax requirements |

### Templates (Complete Code)

| Template | When to Use |
|----------|-------------|
| [Seller.php.md](references/templates/Seller.php.md) | Seller model with Connect integration |
| [SellerOnboardingController.php.md](references/templates/SellerOnboardingController.php.md) | OAuth and onboarding flow |
| [MarketplacePaymentController.php.md](references/templates/MarketplacePaymentController.php.md) | Creating charges with fees |
| [PayoutController.php.md](references/templates/PayoutController.php.md) | Managing seller payouts |
| [ConnectWebhookHandler.php.md](references/templates/ConnectWebhookHandler.php.md) | Webhook event handling |
| [ConnectRoutes.php.md](references/templates/ConnectRoutes.php.md) | Route definitions |

---

## Quick Reference

### Create Connected Account

```php
$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]);
```

### Create Onboarding Link

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

### Destination Charge with Fee

```php
$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,
    ],
]);
```

### Check Account Status

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

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

---

## Best Practices

### DO
- Use Express accounts for most marketplaces
- Implement webhook handlers for all Connect events
- Store transaction records locally
- Handle `account.updated` to track onboarding status
- Use idempotency keys for payment creation
- Test with Stripe CLI and test clocks

### DON'T
- Enable payouts before KYC completion
- Ignore negative balance scenarios
- Skip webhook signature verification
- Hardcode Stripe account IDs
- Forget to handle dispute notifications
- Process refunds without checking seller balance

---

## Laravel 13 Notes

Stripe Connect (`stripe/stripe-php` 21.x, current 21.3) is **Laravel 13 compatible**; the static methods used here (`\Stripe\Account::create()`, `AccountLink::create()`) still exist. Adjustments:

- Connect webhook: exclude `connect/webhook` from `PreventRequestForgery` (see [[laravel-auth]])
- `account.updated` handler: use `Context::add('stripe_account', $accountId)` to propagate into the queue
- PHP 8.3: `final readonly class` for the `Seller` DTO and `PayoutResult`


---
Source attribution: fusengine
Original project: https://github.com/fusengine/agents/blob/755db24bb95882ae4a17b1ada5c8bfa49af394ee/plugins/laravel-expert/skills/laravel-stripe-connect/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Fusengine

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: fusengine
Original project: https://github.com/fusengine/agents/blob/755db24bb95882ae4a17b1ada5c8bfa49af394ee/plugins/laravel-expert/skills/laravel-stripe-connect/SKILL.md
Attribution basis: Recovered original package and original project license at a pinned revision

Fields of work: Marketing, Sales
Roles: Business Development, Customer Success Manager, Growth Marketer, Product Marketer, Sales Engineer
Specialties: API, Backend
Tools: Stripe
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 25823367f22a96312363eeb7e2861a625ac4fe5aec7246dbb18c07b5f4fef7e3
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.