Stripe Connect Marketplace: Guide for Owners and Developers

Stripe Connect is the payments infrastructure layer that lets your marketplace onboard sellers, route payments, collect platform fees, and pay out vendors, all without building KYC, payout logic, or fraud tooling from scratch. Your immediate checklist has three steps: pick your charge model (destination charges or separate charges and transfers), choose your onboarding path (Stripe-hosted or embedded), and create your first test connected account using Accounts v2 in the Stripe Dashboard.

Before writing a single line of production code, run these calls in test mode:

• Create a connected account: POST /v1/accounts with type: express and controller.losses.payments: stripe
• Generate an Account Link: POST /v1/account_links with type: account_onboarding
• Create a Checkout Session with transfer_data.destination pointing to the connected account
• Register a webhook endpoint and confirm you receive account.updated and payment_intent.succeeded

Get those four calls working before anything else. The rest of the integration builds on top of them.

Key Takeaways

Choosing the right charge model and onboarding path before writing production code is the single decision that most determines how fast and how cleanly your Stripe Connect marketplace ships.

Table of Contents

• How does Stripe Connect route money for a marketplace?
• Which connected account type and onboarding path should you use?
• How do you collect fees, manage balances, and pay out sellers?
• What does a minimal Stripe Connect integration actually look like?
• Which webhooks do you need to handle for reliable marketplace operations?
• What KYC, tax, and PCI compliance do U.S. marketplaces need to handle?
• How do you run and scale a Stripe Connect marketplace operationally?
• What are the most common Stripe Connect implementation mistakes?
• When should you hire an engineering partner instead of building in-house?
• What actually causes delays in real marketplace integrations
• Bitrupt builds production-ready Stripe Connect integrations
• Sources

How does Stripe Connect route money for a marketplace?

The essential integration tasks for any Stripe Connect marketplace come down to one architectural decision: who is the merchant of record, and how does money move between the buyer, your platform, and the seller?

Destination charges vs. separate charges and transfers

Destination charges are the simpler model. Your platform charges the buyer, Stripe routes the funds to the connected account, and your application fee is deducted automatically via application_fee_amount. The platform is the merchant of record, which means disputes and refunds land on you first. This model works well for single-seller checkouts where the buyer is paying one vendor per transaction.

Separate charges and transfers give you more separation. You charge the buyer on your platform account, then explicitly create a Transfer to one or more connected accounts after the fact. This model suits multi-seller baskets, subscription splits, or scenarios where you need to hold funds before distributing them. The tradeoff: more API calls, more state to manage, and more responsibility for reconciliation.

Typical money flows by scenario:

• Single-seller checkout: Buyer pays → destination charge → platform deducts application_fee_amount → remainder lands in connected account → Stripe pays out on the connected account’s schedule
• Multi-seller basket: Buyer pays one charge → platform holds funds → platform creates separate transfers to each seller → each seller’s balance updates independently
• Subscription: Recurring charge on the platform → transfer_data routes a portion to the connected account each billing cycle → platform retains the fee

A few product decisions hinge on which model you pick. Refunds on destination charges are initiated from the platform and flow back through the connected account. Disputes on destination charges are the platform’s liability. With separate charges and transfers, the platform bears the chargeback risk on the original charge regardless of whether the transfer has already been sent. Tax reporting responsibilities also differ: the platform receives the 1099-K when it is the merchant of record.

Pro Tip: Treat the charge model decision as architectural, not cosmetic. Switching from destination charges to separate charges and transfers after launch typically requires refactoring your payment flow, your reconciliation logic, and your dispute-handling code. Make this call before you write the first PaymentIntent.

Which connected account type and onboarding path should you use?

For most marketplaces, the right default is Express accounts with embedded onboarding powered by Accounts v2. That combination gives you Stripe-managed KYC, a Stripe-hosted dashboard for your sellers, and enough UI control to keep the experience on-brand, without owning the compliance update cycle yourself.

Stripe’s onboarding documentation recommends hosted or embedded flows for most platforms precisely because maintaining a fully custom onboarding flow means your team absorbs every card-network rule change, identity verification update, and regional requirement change manually.

Standard, Express, and Custom accounts

• Standard: The seller has a full Stripe account and manages their own settings. Lowest integration effort, but you have minimal control over the seller experience and cannot customize payouts.
• Express: Stripe manages KYC and the seller dashboard. You control the onboarding flow and payout timing. The right choice for most two-sided marketplaces.
• Custom: You own the entire UX and compliance flow. Maximum control, maximum engineering cost. Reserve this for platforms with very specific branding requirements or regulatory constraints that Express cannot satisfy.

Onboarding options

Stripe-hosted onboarding (Account Links) generates a single-use URL that redirects the seller to a Stripe-managed form. Setup is minimal. The tradeoff is that you hand off the UX entirely, and hosted onboarding does not work inside embedded webviews, which rules it out for native mobile apps.

Embedded onboarding (Account Sessions + ConnectJS) renders Stripe’s onboarding components inside your own UI. You get theming control, mobile SDK support, and a branded in-app flow. This is the path to choose when seller experience consistency matters.

API onboarding lets you collect every field yourself and submit via the Accounts API. Full control, but you own every compliance update forever.

Accounts v2 vs. Accounts v1

Accounts v2 changes how you interact with connected account requirements. Key differences:

• Requirements are surfaced as currently_due and eventually_due collections, making incremental onboarding straightforward
• The controller object lets you specify who owns losses, statement descriptors, and stripe fee responsibility per account
• Accounts v2 is the recommended path for new integrations; v1 behavior is still supported but lacks the granular controller configuration

Pro Tip: Account Link URLs are single-use and expire quickly. Always authenticate the seller in your own application before generating and redirecting to an Account Link. Store the account ID server-side and never expose it in client-side code. Implement both return_url and refresh_url so sellers who time out can re-enter the flow cleanly.

How do you collect fees, manage balances, and pay out sellers?

The core mechanic is straightforward: you pass application_fee_amount on a destination charge or Checkout Session, and Stripe deducts that amount from the transaction before routing the remainder to the connected account. Your platform balance grows by the fee amount; the connected account balance grows by the remainder.

For destination charges, the required parameters look like this:

PaymentIntent:
  amount: 10000          # $100.00 in cents
  currency: usd
  application_fee_amount: 1500   # $15.00 platform fee
  transfer_data:
    destination: acct_XXXXXXXXXX  # connected account ID

For separate charges and transfers, you create the charge on your platform account first, then create a Transfer explicitly:

Transfer:
  amount: 8500           # amount to send to seller
  currency: usd
  destination: acct_XXXXXXXXXX
  source_transaction: ch_XXXXXXXXXX  # ties the transfer to the original charge

The Stripe Dashboard and platform tooling let you view platform balances, connected account balances, and payout schedules in one place. You can also use Stripe’s platform pricing tool to automate fee logic rather than hardcoding application_fee_amount values per transaction type.

Payouts and payout readiness

Payouts from a connected account to the seller’s bank account happen on Stripe’s default schedule (typically two business days for U.S. accounts) or on a custom schedule you configure. Before payouts can flow, the connected account must pass bank account verification and complete KYC requirements.

Key payout considerations:

• Negative balances: If a refund or dispute exceeds the connected account’s balance, the platform is responsible for covering the shortfall. Build reserve logic or delay payouts on new accounts to protect against this.
• Payout readiness checks: Poll account.payouts_enabled and account.charges_enabled before allowing a seller to go live. If either is false, surface the onboarding requirements to the seller.
• Bank account verification: For U.S. accounts, Stripe uses micro-deposit verification or instant verification via Plaid integration for faster bank linking.

The money flow in sequence: charge created → platform balance credited with fee → transfer created → connected account balance credited → Stripe initiates payout → funds arrive in seller’s bank account.

What does a minimal Stripe Connect integration actually look like?

The Marketplace quickstart provides working code samples for every step below. Use it alongside the Stripe Dashboard’s guided setup to validate each call before moving to the next.

Integration checklist

1. Create your platform account and enable Connect in the Stripe Dashboard
2. Create a connected account (POST /v1/accounts) with the appropriate type and controller settings
3. Generate an Account Link or Account Session to onboard the seller
4. Implement a Checkout Session or PaymentIntent with transfer_data.destination and application_fee_amount
5. Register webhook endpoints for the events listed in the next section
6. Enable payment methods (cards, ACH, wallets) in the Dashboard or via the Payment Methods API
7. Test end-to-end in test mode using Stripe’s test account numbers and test card numbers

Minimal server-side endpoints

Your server needs at least these four endpoints:

• POST /create-account — calls POST /v1/accounts, stores the returned id
• POST /create-account-link — calls POST /v1/account_links, returns the URL to the client
• POST /create-checkout-session — creates a Checkout Session with transfer_data and application_fee_amount
• POST /webhook — receives and verifies Stripe events

Key parameters to get right

Checkout Session (destination charge pattern):
  payment_method_types: [card]
  line_items: [...]
  mode: payment
  payment_intent_data:
    application_fee_amount: 1500
    transfer_data:
      destination: acct_XXXXXXXXXX
  success_url: https://yourplatform.com/success
  cancel_url: https://yourplatform.com/cancel

For subscriptions, add subscription_data.application_fee_percent instead of a flat fee amount, which lets Stripe calculate the fee on each recurring charge automatically.

Testing guidance

Run every flow in test mode first. Create test connected accounts using POST /v1/accounts with test credentials, use Stripe’s test bank account numbers to simulate payouts, and use the Stripe Dashboard’s webhook replay feature to re-send events without triggering real transactions. The stripe-samples GitHub repository contains production-like examples for embedded onboarding, Account Links, Checkout sessions, and webhook handling.

Pre-launch checklist

• [ ] KYC flow tested end-to-end with a test connected account
• [ ] application_fee_amount verified against expected platform economics
• [ ] Payouts tested to a test bank account (confirmed payout.paid event received)
• [ ] Webhook signatures verified server-side on every event
• [ ] Refund flow tested (confirm funds return to buyer and fee is reversed)
• [ ] Dispute handling documented and tested
• [ ] Negative balance scenario tested (refund exceeding connected account balance)
• [ ] Monitoring and alerting configured for payout.failed and account.updated

Which webhooks do you need to handle for reliable marketplace operations?

Stripe’s Connect platform tooling specifies the events your marketplace must handle to stay operationally reliable. Missing even one of these in production means silent failures that are hard to debug after the fact.

Must-handle events

• payment_intent.succeeded — confirm the payment cleared before fulfilling the order
• payment_intent.payment_failed — surface the failure to the buyer and halt fulfillment
• charge.refunded — update your order state and notify the seller
• charge.dispute.created — trigger your dispute response workflow immediately
• payout.created — log the payout initiation for reconciliation
• payout.failed — alert your ops team and notify the seller; investigate the bank account
• transfer.created — confirm the transfer to the connected account was initiated
• transfer.failed — retry logic or manual intervention required
• account.updated — check requirements.currently_due and surface any new onboarding steps to the seller

Webhook security and idempotency

Verify every incoming webhook using Stripe’s signature verification (Stripe-Signature header + your webhook secret). Never process an event without verifying the signature first. Use idempotency keys on all outbound API calls so that retries on network failures do not create duplicate charges or transfers. Implement exponential backoff for any retry logic on failed API calls.

For Connect specifically, you need two webhook endpoints: one for your platform account events and one for connected account events (set connect: true on the endpoint). Events from connected accounts arrive with a different structure and require the connected account’s ID to be extracted from the event object.

Pro Tip: Build a lightweight internal event log that stores the Stripe event ID, type, and your internal order/seller ID alongside the processing status. When a payout fails or a dispute arrives, you can cross-reference Stripe events with your order state in seconds rather than digging through two separate dashboards.

What KYC, tax, and PCI compliance do U.S. marketplaces need to handle?

Stripe handles the heavy lifting of KYC through Accounts v2, but your platform retains responsibility for several compliance obligations that Stripe cannot absorb on your behalf.

What Stripe handles

• Identity verification (government ID, SSN last four, date of birth) for Express and Custom accounts
• Bank account verification
• Ongoing monitoring and re-verification when requirements change
• Card-network rule updates and fraud screening via Stripe Radar

What your platform owns

For U.S. marketplaces, you must collect and verify:

• Legal business name and EIN (for business accounts) or SSN (for sole proprietors)
• Physical address and date of birth for individual verification
• Bank account details for payouts

Stripe recommends incremental onboarding, collecting only currently_due fields first to maximize seller conversion, then requesting eventually_due fields as the seller’s volume grows. This approach reduces drop-off during initial signup without sacrificing compliance completeness over time.

PCI scope

Using Stripe-hosted Checkout or Stripe.js keeps your platform out of PCI scope for card data. If you collect raw card numbers directly, you take on PCI DSS Level 1 obligations, which require annual audits and quarterly scans. The practical advice: use Stripe’s hosted or embedded payment components and stay out of card data entirely.

Tax reporting

U.S. platforms that process payments for sellers may have 1099-K reporting obligations depending on transaction volume and count. The IRS thresholds for 1099-K reporting have been in flux; consult a qualified tax professional to confirm your current obligations before going live. Stripe’s tax reporting tools can generate 1099 forms for connected accounts, but the platform is responsible for accuracy and timely delivery.

For platforms expanding internationally, cross-border tax obligations add another layer. EU marketplaces, for example, face VAT intermediary requirements under the OSS scheme. Understanding VAT intermediary services before you enable cross-border payouts saves significant remediation cost later.

Always authenticate the account holder in your own system before generating an Account Link. This prevents unauthorized parties from completing onboarding under another seller’s account ID, which is both a security risk and a KYC integrity issue.

How do you run and scale a Stripe Connect marketplace operationally?

Automation and observability are the two levers that let you scale without proportionally growing your ops headcount. A marketplace with 50 sellers can be managed manually; one with 5,000 cannot.

Operational priorities

• Automate onboarding triggers: Send Account Link emails automatically when a seller signs up. Use account.updated webhooks to detect when onboarding stalls and send follow-up nudges.
• Use embedded flows for brand control: When seller experience consistency matters, embedded Account Sessions let you theme the onboarding UI to match your platform without building a custom compliance flow.
• Centralize reconciliation: Pull Stripe balance transactions via the API daily and reconcile against your internal ledger. Discrepancies are far easier to catch at day-end than at month-end.
• Use Stripe Radar: Enable Radar rules for fraud screening on incoming payments. For high-risk categories, add custom Radar rules based on your platform’s specific fraud patterns.
• Automate platform fee logic: Use Stripe’s platform pricing tool to define fee rules rather than hardcoding application_fee_amount in every payment call. This makes fee changes a configuration update, not a code deploy.

Refunds and reserves

Refund policy should be defined before launch, not after the first dispute. For destination charges, refunds are initiated from the platform and reverse the transfer to the connected account. For separate charges and transfers, you refund the original charge and create a separate reversal on the transfer. Keep a reserve on new connected accounts (delay payouts by 7–14 days) until the seller has a track record, which protects the platform from negative balance exposure on early refunds.

Pro Tip: Phase your rollout deliberately. Start with a single payment method (cards only) in your primary market. Once payouts are stable and your webhook handling is proven, add ACH and digital wallets. Only then enable cross-border payouts, which introduce currency conversion, local payout rails, and additional KYC requirements. Each phase should have a defined go/no-go checklist before the next one opens.

What are the most common Stripe Connect implementation mistakes?

Most marketplace integrations that stall in QA or fail in production share the same handful of root causes. Knowing them upfront is cheaper than discovering them after launch.

High-impact pitfalls

• Wrong charge model chosen late: Switching from destination charges to separate charges and transfers post-launch requires refactoring payment flows, reconciliation, and dispute handling simultaneously. Make this decision at architecture time.
• Missing webhook handlers: Skipping payout.failed or account.updated means your ops team learns about problems from angry sellers, not from your own monitoring.
• Not testing negative balances: Most teams test the happy path (charge succeeds, payout succeeds) but never simulate a refund that exceeds the connected account’s balance. This scenario will happen in production.
• Collecting PII incorrectly: Passing raw identity data through your own servers when Stripe’s hosted or embedded flows would handle it creates unnecessary PCI and data-privacy exposure.
• Skipping idempotency keys: Network timeouts on payment calls without idempotency keys can create duplicate charges. Every POST to the Stripe API that creates a resource should include an Idempotency-Key header.
• Not implementing refresh_url: If a seller’s Account Link expires before they complete onboarding, they land on a dead URL. Always implement refresh_url to regenerate a fresh link.

Pre-launch go/no-go checklist

• [ ] KYC onboarding tested with real test accounts; charges_enabled and payouts_enabled confirmed true after completion
• [ ] Webhook signatures verified in production (not just test mode)
• [ ] Payouts tested to real bank accounts in staging
• [ ] Monitoring alerts configured for payout.failed, dispute.created, and onboarding stall rate
• [ ] Refund and dispute workflows documented and assigned to an owner
• [ ] Negative balance scenario tested and reserve policy implemented
• [ ] Tax reporting obligations confirmed with a qualified tax professional

For platforms handling document-heavy KYC (e.g., contractor marketplaces requiring license verification), supplementing Stripe’s built-in verification with a dedicated tool like DocuPOW Flow for document automation can reduce manual review time significantly.

When should you hire an engineering partner instead of building in-house?

Two thresholds make the hire-vs-build decision straightforward. If your engineering team has fewer than three senior engineers who have shipped a payments integration before, or if your marketplace requires cross-border payouts, regulated financial rails, or complex tax reporting from day one, hiring a specialist partner is faster and lower-risk than building in-house.

Decision checklist

Ask these questions before committing to an in-house build:

• Engineering hours available: A production-ready Stripe Connect integration with embedded onboarding, webhook handling, reconciliation, and dispute workflows typically requires 400–800 engineering hours depending on complexity. Do you have that capacity in the next 90 days?
• Required integrations: Does your marketplace need bank connectivity beyond Stripe (ACH pull, wire transfers), tax reporting automation, or localization for non-U.S. markets? Each adds significant scope.
• SLA requirements: If your marketplace handles high-value transactions, what is your acceptable downtime for payout failures? Engineering a reliable retry and alerting system takes time that is easy to underestimate.
• Cross-border payouts: Enabling payouts in multiple currencies and countries requires understanding local payout rails, currency conversion, and additional KYC requirements per market.

Vendor tradeoffs

Building in-house gives you full IP ownership and deep institutional knowledge of your payment stack. The cost is time: a team learning Stripe Connect from scratch will hit every pitfall in the previous section at least once. An experienced partner brings pattern recognition from prior integrations, which compresses the timeline and reduces the risk of architectural mistakes that are expensive to undo.

For marketplaces that need to move fast, a discovery sprint with a specialist team (typically one to two weeks) to scope the integration, validate the charge model choice, and produce a technical spec is a low-cost way to de-risk the build before committing to a full engagement. From there, a production integration sprint of six to twelve weeks with an experienced team can take you from zero to a live, monitored marketplace payment system.

Bitrupt’s marketplace engineering practice covers exactly this scope: custom Connect integrations, embedded onboarding, payout infrastructure, and ongoing ops support. The team works in senior-only engineering pods, which means no ramp-up time on the fundamentals and a 24-hour response SLA on critical issues.

What actually causes delays in real marketplace integrations

The single most consequential early decision in any Stripe Connect marketplace build is the charge model, and it is almost always made too casually. Teams pick destination charges because the documentation example uses them, then discover six months later that their multi-seller basket scenario requires separate charges and transfers, and the refactor touches every layer of the stack.

The second most common delay source is webhook handling. Sample apps and quickstarts show the happy path. Production requires handling payout.failed, dispute.created, and account.updated with real business logic behind each one, not just a 200 OK response. Teams that treat webhooks as an afterthought spend weeks in QA chasing state inconsistencies that a proper event-driven design would have prevented.

Working with Stripe’s official sample apps and the Accounts v2 quickstart blueprints compresses the learning curve significantly. The patterns in those repos reflect real production decisions, not toy examples.

Bitrupt builds production-ready Stripe Connect integrations

Marketplace payment infrastructure is one of the highest-leverage investments you can make early, and one of the most expensive to rebuild if the architecture is wrong. Bitrupt’s fintech engineering team has shipped Stripe Connect integrations for two-sided marketplaces across multiple verticals, handling everything from embedded onboarding and application fee logic to cross-border payout infrastructure and dispute workflows.

Engagements start with a focused discovery sprint (one to two weeks) that validates your charge model, maps your webhook event requirements, and produces a scoped integration plan. From there, a senior engineering pod takes the build to production, with ongoing ops support available after launch. Every engagement includes a 24-hour response SLA and full IP transfer. If you are ready to move from architecture decision to working integration, talk to the Bitrupt team about a discovery sprint.

Sources

These are the canonical sources for the flows covered in this guide. Developers should start with the quickstart and sample apps; product and ops owners will get more from the onboarding overview and platform pricing docs.

For developers:

• Build a marketplace

For product and ops owners:

Recommended

• Plaid API Integration: Developer Quickstart Guide | Bitrupt
• FitSono Dual-Portal Fitness App Case Study | Bitrupt | Bitrupt
• Bitrupt — Software Development Agency | Mobile, Web & Enterprise