Building a three-sided marketplace payment system with Stripe Connect

The Business Model

Spa Space operated a three-sided marketplace where:

• Wellness providers (therapists, practitioners) delivered services
• Venues (spas, hotels, wellness centres) hosted the services
• The platform connected them and handled bookings

Each booking generated revenue that needed to be distributed fairly among all three parties - a payment complexity that goes well beyond standard e-commerce.

The Payment Problem

Traditional payment systems are designed for two parties: buyer and seller. A three-sided marketplace breaks this model:

• Multiple beneficiaries per transaction
• Variable splits depending on service type and agreements
• Platform fee retention before distribution
• Booking-linked payments with deposits, balances, and refunds
• Compliance requirements for money transmission

The Complexity

• Each booking could involve different providers and venues with different fee structures
• Payments needed to match booking states (deposit at booking, balance after service)
• Cancellation and refund scenarios had to handle partial payments correctly
• Regulatory compliance required proper fund segregation
• The business model was still evolving, requiring flexibility in split configurations

Our Approach

We designed a payment architecture using Stripe Connect with separate connected accounts for providers and venues, enabling compliant multi-party payments with the platform as the orchestrator.

Connected Account Structure

Rather than aggregating funds centrally (which creates regulatory complexity), we used Stripe Connect's model:

• Platform account for overall orchestration and fee collection
• Provider accounts (Express) for therapist payouts
• Venue accounts (Express) for venue payouts

This structure meant funds flowed directly to recipients through Stripe's regulated infrastructure, reducing compliance burden on the platform.

Payment Flow Design

Customer Payment
       |
       v
  Stripe Checkout
       |
       v
  Platform Fee Retained (10-15%)
       |
       +--> Provider Account (service fee)
       |
       +--> Venue Account (venue fee)

The payment was split at the point of transaction using Stripe's transfer_data and application_fee_amount parameters, ensuring clean fund segregation.

Booking-Linked Settlement

Payments were tightly integrated with booking state:

1. Booking created - Payment intent created with calculated splits
2. Customer pays deposit - Partial capture, funds held
3. Service completed - Final balance captured and settled
4. Booking cancelled - Appropriate refunds issued to correct parties

Implementation Details

• Dynamic split calculation based on service type, provider agreement, and venue terms
• Idempotency to prevent duplicate charges on retries
• Webhook handling for Stripe events (payment succeeded, failed, disputed)
• Reconciliation to match Stripe transactions to booking records
• Payout scheduling aligned with business cash flow requirements

Payment Distribution

• Three beneficiaries supported per transaction
• Platform fees retained automatically at payment time
• Compliant fund flow through Stripe's regulated infrastructure

Operational Benefits

• Automated settlements - no manual payment processing
• Clear audit trail - every payment linked to a booking
• Reduced disputes - transparent split calculations
• Scalable model - could handle any volume without process changes

Business Flexibility

• Configurable splits - fee structures could be adjusted per provider or venue
• Multiple payment models - supported deposit + balance, full prepayment, and pay-on-arrival
• Refund handling - automated proportional refunds when bookings cancelled

Why Stripe Connect?

Several options exist for marketplace payments, but Stripe Connect offered key advantages:

1. Regulatory compliance - Stripe handles money transmission licensing
2. Connected accounts - Direct relationships with recipients, not aggregated funds
3. Flexible payouts - Platform controls payout timing
4. Global reach - Supports international expansion
5. Developer experience - Well-documented APIs and testing tools

Split Calculation Service

The split calculation was implemented as a dedicated service:

SplitCalculationService
  - getProviderRate(providerId, serviceType)
  - getVenueRate(venueId)
  - getPlatformFee(bookingValue)
  - calculateSplit(booking) -> { platform, provider, venue }

This separation meant business rules for splits could evolve independently of the payment integration.

Handling Edge Cases

The implementation addressed several complex scenarios:

Partial refunds: When a booking was partially refunded (e.g., service shortened), the refund was proportionally distributed based on original splits.

Disputes: Chargebacks were handled through Stripe's dispute process, with the platform retaining evidence of service delivery.

Failed payouts: If a connected account could not receive funds (e.g., verification incomplete), funds were held and retried automatically.

Multi-currency: While initial launch was UK-only (GBP), the architecture supported adding currencies for international expansion.

Webhook Reliability

Stripe webhooks were processed through a queue to ensure:

• At-least-once processing - failed handlers retried
• Ordering - events processed in sequence per booking
• Idempotency - duplicate events handled gracefully

Lessons Learned

1. Test with Stripe's test mode extensively - edge cases in payments are expensive to discover in production
2. Build reconciliation from day one - matching Stripe records to internal state saves debugging time
3. Plan for disputes - have evidence collection built into the booking flow
4. Consider payout timing - provider and venue cash flow expectations matter to business relationships