Advanced
How to build connect marketplace integrations on Stripe
Quick Answer
Stripe Connect allows you to build marketplace integrations by creating connected accounts for your sellers and facilitating payments between buyers and sellers. You'll need to set up your platform account, implement OAuth flows for seller onboarding, and handle payment processing with proper fee structures.
Prerequisites
- Stripe account with Connect enabled
- Basic understanding of webhooks and APIs
- Development environment with HTTPS
- Knowledge of OAuth 2.0 flow
1
Configure Stripe Connect Settings
Navigate to your Stripe Dashboard and go to Connect → Settings. Choose your integration type: Standard (easiest), Express (balanced), or Custom (full control). Enable OAuth under platform settings and add your redirect URIs. Set up your branding and application information that connected accounts will see during onboarding.
Tip
Start with Express accounts for faster onboarding while maintaining compliance control.
2
Implement Connected Account Creation
Create connected accounts using the Stripe API:
Store the returned
stripe.accounts.create({
type: 'express',
country: 'US',
email: 'seller@example.com',
capabilities: {
card_payments: {requested: true},
transfers: {requested: true}
}
});Store the returned
account_id in your database linked to the seller's profile.Tip
Always specify the required capabilities upfront to avoid issues during onboarding.
3
Set Up Account Onboarding Flow
Create account links for seller onboarding:
Redirect sellers to the returned url to complete their verification process. Handle the return flow to check account status using
stripe.accountLinks.create({
account: 'acct_connected_account_id',
refresh_url: 'https://yourapp.com/reauth',
return_url: 'https://yourapp.com/return',
type: 'account_onboarding'
});Redirect sellers to the returned url to complete their verification process. Handle the return flow to check account status using
stripe.accounts.retrieve().4
Configure Webhook Endpoints
Set up webhook endpoints in Developers → Webhooks. Create separate endpoints for account events (account.updated, account.application.deauthorized) and Connect events. Enable events like
account.updated, payment_intent.succeeded, and transfer.created. Verify webhook signatures using:stripe.webhooks.constructEvent(
payload, signature, endpointSecret
);Tip
Use different webhook endpoints for account events and payment events for better organization.
5
Implement Payment Processing
Create payments on behalf of connected accounts using destination charges or separate charges and transfers:
Set your
// Destination charge method
stripe.paymentIntents.create({
amount: 2000,
currency: 'usd',
transfer_data: {
destination: 'acct_connected_account_id',
amount: 1800 // minus platform fee
}
});Set your
stripe_account header when creating charges directly on connected accounts.Tip
Destination charges are simpler but direct charges give you more control over the payment flow.
6
Handle Platform Fees and Payouts
Configure your fee structure by either collecting application fees or using Stripe's application_fee_amount parameter. For manual payouts, create transfers:
Monitor payout schedules in Connect → Accounts and handle failed transfers through webhooks.
stripe.transfers.create({
amount: 1000,
currency: 'usd',
destination: 'acct_connected_account_id'
});Monitor payout schedules in Connect → Accounts and handle failed transfers through webhooks.
Tip
Consider automatic vs manual payout schedules based on your marketplace's cash flow needs.
7
Test and Monitor Integration
Use Stripe's test mode with test connected accounts. Test the complete flow: account creation, onboarding, payments, and payouts. Monitor your integration using Connect → Activity and set up alerts for failed transfers or account issues. Implement proper error handling for declined payments and account verification failures.
Tip
Create test scenarios for different account states (pending, restricted, enabled) to ensure robust error handling.
Troubleshooting
Connected account onboarding fails or gets stuck
Check the account's requirements object via API to see what information is missing. Ensure all required fields are collected and capabilities are properly requested during account creation.
Payments fail with 'account not found' error
Verify you're using the correct
stripe_account header and that the connected account is fully onboarded. Check account status is charges_enabled: true before processing payments.Platform fees not appearing in dashboard
Ensure you're using
application_fee_amount parameter in PaymentIntents or setting application_fee in destination charges. Check that your Connect settings allow fee collection.Webhook events not being received
Verify webhook endpoint URLs are accessible via HTTPS and return 200 status codes. Check Webhook logs in dashboard for delivery failures and ensure you're listening for the correct event types.
Ready to get started with Stripe?
Put this tutorial into practice. Visit Stripe and follow the steps above.
Visit Stripe →