Designing a Production-Ready Stripe Connect Payment Flow for Marketplaces
shares
Marketplaces don’t behave like normal e-commerce.
In a typical checkout, a customer pays, the seller ships, and the transaction is done. Simple, predictable, and easy to model.
Marketplaces are different. Vendors can accept or reject items. Orders may be partially fulfilled. Commissions depend on what actually ships, not what was originally ordered.
Yet many platforms still treat marketplace payments like standard checkouts.
That mistake usually shows up later as refunds, accounting drift, and operational headaches.
In this post, we’ll walk through a production-tested Stripe Connect payment architecture that aligns money movement with real business decisions — using authorization-based payments, delayed capture, and deterministic fee calculation.
The Marketplace Payment Reality
At a high level, our marketplace flow looked straightforward:
- A customer places an order
- The platform processes payment
- Vendors independently accept or reject items
- The platform earns a commission
- Vendors receive the rest
On paper, this is a textbook use case for Connect.
The complexity isn’t what happens — it’s when money should actually move.
In marketplaces, business decisions happen after checkout. Payments shouldn’t get ahead of those decisions.
The First Mistake: Capturing Too Early
Our initial implementation followed Stripe’s most common example:
This pattern is well documented, quick to implement, and works perfectly for single-seller stores.
In a marketplace, it fails fast.
Why Immediate Capture Breaks Marketplaces
Capturing funds immediately created a cascade of problems:
- Customers were charged before vendors reviewed items
- Rejected items triggered refunds
- Platform fees were calculated on totals that later changed
- Stripe reports became hard to reconcile
- Refund and adjustment logic grew out of control
None of this was a Stripe issue.
It was an architectural one.
Payment finality was happening before business logic was complete.
The Shift That Fixed Everything: Authorization First
The fix wasn’t complex — but it required changing how we thought about checkout.
Instead of capturing money immediately, we separated authorization from capture.
The PaymentIntent was created with manual capture enabled:
From Stripe’s perspective, this means:
- The payment is authorized
- Funds are reserved on the customer’s card
-
The PaymentIntent enters
requires_capture - No money moves yet
This single change unlocked the rest of the system.
Aligning Payment State with Business State
After checkout:
- The full order amount is authorized
- Vendors independently accept or reject items
- The platform tracks item-level decisions internally
- Stripe remains untouched
Principle: Payment state should never advance faster than business state.
What Happens When Vendors Decide
Item Acceptance
When a vendor accepts an item:
- The item is marked as accepted
- The related transaction row is locked to prevent race conditions
- No Stripe action is taken
If other items are still pending, the system simply waits.
No partial captures. No recalculations. No side effects.
Item Rejection
When an item is rejected:
- The item is marked as rejected
- Its value is excluded from the final payable total
- Fees and delivery costs are recalculated internally
- Stripe is still not contacted
Accepted or rejected, the rule never changes:
Stripe is called exactly once, with final numbers.
Finalization: One Clean Payment Decision
Once all items reach a terminal state, the platform finalizes the payment.
Case 1: All Items Rejected
If nothing is accepted:
- The authorization is released
- The customer is never charged
- No refunds are needed
Case 2: One or More Items Accepted
If some items are accepted:
- The platform calculates the accepted total
- Platform commission is computed
- Stripe fees apply automatically
- Only the accepted amount is captured
This results in one clean, auditable Stripe transaction.
In production, this step also handles authorization expiry and retry logic — but the core model stays the same.
Why Platform Fees Must Be Applied at Capture Time
We learned quickly that fee timing matters.
Applying platform fees earlier caused:
- Incorrect deductions when items were rejected
- Capture failures due to mismatched totals
- Confusing Stripe dashboards and exports
Fees are a consequence of fulfillment, not intent.
By applying them at capture time:
- Platform revenue reflects real outcomes
- Vendors are paid correctly
- Accounting stays predictable
Stripe handles the rest — transferring net funds to vendors and retaining the platform’s commission automatically.
No internal wallets. No manual transfers. No reconciliation surprises.
Why This Architecture Holds Up in Production
This model gives you:
- Full control over payment timing
- Safe handling of partial fulfillment
- Accurate, auditable commissions
- Clean Stripe reporting
- Simpler refunds and disputes
Most importantly, customers are charged only for what vendors actually accept.
Closing Thoughts
Stripe Connect is powerful, but marketplace payments demand deliberate design.
Treating them like standard e-commerce leads to refunds, accounting drift, and operational risk. For platforms with vendor approvals, partial fulfillment, or commissions, authorization-first payments with delayed capture should be the default.
Align payment state with business reality — and everything downstream becomes simpler, safer, and easier to operate.