fusengine/laravel-stripe-connect

Laravel Stripe Connect

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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