laravel-stripe-connect

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
Onboarding	KYC process for sellers	onboarding.md
Application Fee	Platform's commission on payments	fees-commissions.md
Destination Charge	Payment with automatic transfer to seller	payment-flows.md
Payout	Transfer from Stripe balance to bank	payouts.md

---

Reference Guide

Concepts (WHY & Architecture)

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

Templates (Complete Code)

Template	When to Use
Seller.php.md	Seller model with Connect integration
SellerOnboardingController.php.md	OAuth and onboarding flow
MarketplacePaymentController.php.md	Creating charges with fees
PayoutController.php.md	Managing seller payouts
ConnectWebhookHandler.php.md	Webhook event handling
ConnectRoutes.php.md	Route definitions

---

Quick Reference

Create Connected Account

$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

$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

$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

$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 16.x) est compatible Laravel 13. Adaptations :

• Webhook Connect : exclure connect/webhook de PreventRequestForgery (voir [[laravel-auth]])
• account.updated handler : utiliser Context::add('stripe_account', $accountId) pour propager dans la queue
• PHP 8.3 : final readonly class pour Seller DTO et PayoutResult