Stripe Connect is one of the most powerful yet intimidating APIs for developers building marketplace and platform businesses. If you're building any application where money needs to move between your platform and multiple users—creators, vendors, freelancers—you need Stripe Connect.
But the documentation is dense. The implementation feels complex. And mistakes here cost you money.
This guide breaks down Stripe Connect into digestible pieces and shows you exactly how to integrate it into your platform.
What Is Stripe Connect?
Stripe Connect is a platform payment system. It lets you: Accept payments from customers, automatically split payments between your platform and connected sellers, handle payouts to multiple vendors, and manage marketplace dynamics without owning customer relationships.
Think of it as the payment infrastructure behind apps like DoorDash, Etsy, or Airbnb.
Core Components: Accounts API (create and manage connected accounts), Transfers API (move money between accounts), Payouts API (distribute earnings to connected accounts), and OAuth (let users connect their own Stripe accounts).
Step 1: Understanding the Three Account Models
Stripe Connect offers three account types. Choose wrong and you'll have to refactor later.
Standard Accounts (OAuth)
User creates their own Stripe account. You request permission via OAuth. Minimal KYC on your side (Stripe handles it). Best for: Marketplaces where vendors are established businesses.
const stripeAuthUrl = https://connect.stripe.com/oauth/authorize?client_id=${STRIPE_CLIENT_ID}&state=${state}&scope=read_write;
Express Accounts (Fully Managed Onboarding)
Simplified account creation. Stripe collects minimal info upfront. You can request additional info later. Best for: Platforms with simple vendor requirements.
const account = await stripe.accounts.create({ type: 'express', country: 'US', email: 'vendor@example.com', capabilities: { card_payments: { requested: true }, transfers: { requested: true } } });
Custom Accounts (Maximum Control)
You handle all KYC and verification. Requires PCI compliance if you collect payment details. Most responsibility on your platform. Best for: Enterprise marketplaces with custom requirements. For most developers, Express accounts are the sweet spot. They balance simplicity with functionality.
Step 2: Setting Up Express Account Onboarding
Create an Express account when a vendor joins your platform:
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY); async function createConnectedAccount(vendorData) { const account = await stripe.accounts.create({ type: 'express', country: 'US', email: vendorData.email, capabilities: { card_payments: { requested: true }, transfers: { requested: true } }, business_profile: { url: vendorData.website, support_email: vendorData.supportEmail } }); await saveConnectedAccountId(vendorData.userId, account.id); return account.id; }
Step 3: Create an Account Link for Onboarding
After creating the account, generate an account link. This redirects the vendor to Stripe's onboarding flow:
async function generateOnboardingLink(accountId, refreshUrl) { const accountLink = await stripe.accountLinks.create({ account: accountId, type: 'account_onboarding', return_url: refreshUrl, refresh_url: refreshUrl }); return accountLink.url; }
The vendor clicks this link, completes Stripe's onboarding, and returns to your app.
Step 4: Handling Payments with Charge-on-Behalf
When a customer pays through your platform, use charge-on-behalf to automatically split the payment:
async function createPaymentWithSplit(amount, vendorAccountId, platformFee) { const charge = await stripe.charges.create({ amount: amount, currency: 'usd', source: 'tok_visa', on_behalf_of: vendorAccountId, application_fee_amount: platformFee, description: 'Order payment' }); return charge; }
Critical: Always use on_behalf_of parameter. This tells Stripe to route the charge through the connected account while deducting your application fee.
Step 5: Transferring Funds to Vendors
After charging the customer, transfer the vendor's earnings to their account:
const vendorEarnings = amount * 0.8; const platformFee = amount * 0.2; await transferFundsToVendor(accountId, vendorEarnings, 'Order #12345 payout');
Step 6: Handling Payouts
Vendors don't automatically receive funds. They need to request payouts (or you can enable automatic payouts):
async function enableAutomaticPayouts(accountId) { await stripe.accounts.update(accountId, { settings: { payouts: { statement_descriptor: 'Your Platform Payout', schedule: { interval: 'daily' } } } }); }
Step 7: Implementing Webhooks
Stripe sends events about charges, transfers, and account changes. Listen for critical events:
app.post('/webhook', (req, res) => { const event = stripe.webhooks.constructEvent( req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET ); switch(event.type) { case 'charge.succeeded': await logPayment(event.data.object); break; case 'account.updated': await updateVendorStatus(event.data.object.id); break; } res.json({received: true}); });
Best Practices for Stripe Connect Integration
1. Always Store Account IDs: Never regenerate connected account IDs. Store them in your database immediately after creation.
2. Implement Idempotency Keys: Prevents duplicate charges if requests fail and retry.
3. Handle Disputes: Connected accounts can have payment disputes. Listen for charge.dispute.created webhooks. 4. Validate Account Status: Check charges_enabled and payouts_enabled before processing. 5. Implement Proper Error Handling: Differentiate between account_not_ready errors and infrastructure issues.
Real-World Scenario: Marketplace Payment Flow
Here's how Fintech app Development teams implement a complete payment flow: Customer places order → Platform charges customer + deducts fee → Webhook confirms charge → Platform transfers vendor's earnings → Vendor reviews balance in dashboard → Automatic payout daily/weekly to vendor's bank account → Disputes handled and vendor notified.
Common Integration Mistakes
Mistake 1: Forgetting on_behalf_of parameter. Without it, the charge goes to your account, not the vendor's.
Mistake 2: Not handling charges_enabled: false. Some vendors don't complete onboarding.
Mistake 3: Transferring immediately after charge. Wait for charge to settle using webhooks. Mistake 4: Not storing Stripe account IDs. You can't retrieve this later easily.
Conclusion
Stripe Connect is complex, but the pattern is consistent: Create express accounts, charge on behalf of vendors, automatically transfer earnings, handle webhooks for status updates, and enable automatic payouts.
Once you understand the flow, integration becomes straightforward. Start with Express accounts, implement proper error handling, and listen to webhooks. Your marketplace will have enterprise-grade payment infrastructure.
The hardest part isn't Stripe. It's thinking through your platform's payment logic before building. Get that right, and Stripe Connect handles the rest.
Top comments (0)