Stripe Connect — Complete Guide to Platform Payments

In this tutorial, you will learn about Stripe Connect. We cover key concepts, practical examples, and best practices to help you master this topic.

Stripe Connect enables platforms to accept payments on behalf of third parties, route funds between sellers and buyers, and manage onboarding, compliance, and payouts for marketplace businesses.

What You'll Learn

• Connect account types: Standard, Express, Custom
• Onboarding connected accounts and collecting verification
• Creating payments and splitting funds between platform and seller

Why It Matters

Building a marketplace payment system requires handling KYC/AML compliance, fund routing, dispute management, and tax reporting. Stripe Connect provides these as a managed service.

Real-World Use

A cybersecurity services marketplace built on Durga Antivirus technology uses Stripe Connect: buyers pay the platform, funds are split (platform fee + seller payout), and sellers receive automatic payouts to their bank accounts.

flowchart LR
    B["Buyer"] --> P["Platform"]
    P --> S["Stripe Connect"]
    S --> A["Seller Account"]
    P --> F["Platform Fee"]
    S --> O["Payout to Seller"]
    style S fill:#dbeafe,stroke:#2563eb

Code Examples

import stripe
stripe.api_key = 'sk_test_...'

# Create a connected account
account = stripe.Account.create(
    type='express',
    country='US',
    email='seller@example.com',
    capabilities={
        'card_payments': {'requested': True},
        'transfers': {'requested': True},
    },
)

# Generate onboarding link
link = stripe.AccountLink.create(
    account=account.id,
    refresh_url='https://platform.com/reauth',
    return_url='https://platform.com/complete',
    type='account_onboarding',
)
print(f"Onboarding URL: {link.url}")

Expected output: Express account created with onboarding link for the seller to complete verification.

# Payment with automatic split
import stripe
stripe.api_key = 'sk_test_...'

payment_intent = stripe.PaymentIntent.create(
    amount=10000,  # $100.00
    currency='usd',
    application_fee_amount=1500,  # $15.00 platform fee
    transfer_data={
        'destination': 'acct_connected_seller',
    },
)

print(f"Payment: {payment_intent.id}")
print(f"Platform fee: ${payment_intent.application_fee_amount / 100}")
print(f"Seller gets: ${(payment_intent.amount - payment_intent.application_fee_amount) / 100}")

Expected output: Payment of $100 created; $15 goes to platform, $85 transfers to seller.

// Connect onboarding with webhook handling
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const express = require('express');
const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  switch (event.type) {
    case 'account.updated':
      const account = event.data.object;
      if (account.payouts_enabled) {
        console.log(`Seller onboarded: ${account.id}`);
        updateSellerStatus(account.id, 'active');
      }
      break;
    case 'payout.paid':
      console.log('Payout sent:', event.data.object.id);
      break;
  }

  res.json({ received: true });
});

Expected output: Webhook handles account updates and payout events for connected accounts.

Common Mistakes

1. Choosing Wrong Account Type

Standard accounts require Stripe onboarding; Express is Stripe-hosted but branded; Custom is fully white-label. Choose based on UX requirements.

2. Not Handling Onboarding Failures

Sellers may not complete onboarding. Track onboarding status via Webhooks and prompt incomplete sellers.

3. Incorrect Fee Calculation

Platform fees must be less than the total amount. Calculate fees server-side to prevent manipulation.

4. Ignoring Dispute Handling

Disputes are debited from the platform, not the seller. Have a dispute resolution Process and reserve funds.

5. Not Testing with Test Mode Accounts

Create test connected accounts with stripe fixtures to verify the full payment flow before going live.

Practice Questions

1. What are the three Connect account types and their differences?
2. How does payment splitting work with Stripe Connect?
3. Why must you handle the account.updated webhook?
4. Who bears the cost of disputes in Connect?
5. What is the purpose of the application_fee_amount?

Answers:

1. Standard (Stripe onboarding), Express (Stripe-hosted, minimal), Custom (white-label, full control).
2. PaymentIntent with transfer_data.destination routes funds; application_fee_amount defines platform cut.
3. The webhook notifies when a seller completes onboarding or their verification status changes.
4. The platform bears dispute costs. Have a dispute resolution policy and seller fund reserves.
5. It deducts the platform fee from the payment before transferring the remainder to the seller.

Challenge: Build a freelance services marketplace: sellers sign up via Express onboarding, buyers create PaymentIntents with automatic splits (15% platform fee, 85% to seller), handle disputes, and process weekly automatic payouts.

FAQ

Mini Project

Build a marketplace where service providers onboard via Stripe Connect Express, customers book and pay, the platform takes a 10% fee, and providers receive payouts. Include: onboarding flow, payment creation, webhook handling for account updates and payouts.

What's Next

Learn about Stripe Payouts API for managing seller payouts, or explore Stripe Payment Links for simpler checkout flows.