Marketplace Payment Architecture

Marketplace payments are complex because you're handling money on behalf of others—you're acting as an intermediary, not the merchant.

Key challenges: - Regulatory: Money transmission licenses in many jurisdictions - Escrow: Holding funds safely until release conditions met - Split payments: Dividing payments between multiple parties - Seller management: KYC, onboarding, payouts

Why use a platform (MangoPay, Stripe Connect): - They hold the money transmission license - They handle regulatory compliance - They provide escrow infrastructure - You focus on your marketplace, not payments

Money flow overview: 1. Buyer pays for order 2. Platform holds funds in escrow 3. Order fulfilled/delivered 4. Platform releases funds to seller 5. Platform takes commission

MangoPay uses a wallet-based architecture designed specifically for marketplaces.

Core objects:

Users: Buyers and sellers - Natural (individual) or Legal (business) - KYC verification for payout capability - Can have multiple wallets

Wallets: Hold funds - Each user can have multiple wallets - Different currencies if needed - Balance tracked in real-time

PayIns: Money entering platform - Card payments - Bank transfers - Direct debit - Funds arrive in buyer's wallet

Transfers: Moving between wallets - Buyer wallet → Seller wallet - Can split across multiple wallets - Commission deducted during transfer

PayOuts: Money leaving platform - Wallet → Bank account - Only for verified sellers - Settlement in 1-3 business days

Typical flow: 1. PayIn: Buyer pays €100 → Buyer wallet 2. Transfer: €90 to Seller wallet, €10 to Platform wallet 3. PayOut: €90 from Seller wallet → Seller bank account

Stripe Connect offers different account types with varying levels of platform control.

Standard accounts: - Sellers have full Stripe accounts - Sellers manage their own dashboard - Limited platform control - Sellers handle their own tax reporting

Express accounts: - Simplified onboarding flow - Platform-branded experience - Platform manages most settings - Good balance of control and simplicity

Custom accounts: - Full platform control - Build your own dashboard - Handle compliance communication - Most flexibility, most responsibility

When to choose Stripe Connect: - Already using Stripe for direct payments - Need global reach (195+ countries) - Want unified payment stack - Prefer Stripe's developer experience

When to choose MangoPay: - European-focused marketplace - Need robust escrow/wallet features - Complex fund holding requirements - Prefer explicit wallet-based model

Sellers must be verified before receiving payouts—regulatory requirement, not optional.

Verification levels:

Basic (low limits): - Name and email - Limited transaction amounts - No payout capability

Verified (full capability): - Identity verification (KYC) - Business verification (if applicable) - Bank account validation - Full payout access

Required information (individuals): - Full legal name - Date of birth - Address - Government ID - Proof of address (sometimes)

Required information (businesses): - Legal entity name and type - Registration number - Registered address - Beneficial owner information - Articles of incorporation

Implementation tips: - Collect information progressively - Allow selling before full verification (with limits) - Clear communication about requirements - Handle verification failures gracefully

Escrow protects both buyers and sellers by holding funds until conditions are met.

Common escrow patterns:

Time-based release: - Hold for X days after delivery - Automatic release if no dispute - Simple to implement

Confirmation-based release: - Buyer confirms receipt - Explicit release action required - Risk of buyer not confirming

Milestone-based release: - Partial releases at project stages - Good for services/freelance - More complex to implement

Escrow implementation: 1. PayIn creates buyer wallet balance 2. Transfer to escrow wallet (or seller wallet with hold) 3. Wait for release condition 4. Complete transfer or release hold 5. Handle disputes/refunds if needed

Dispute handling: - Define clear policies - Document evidence requirements - Build dispute resolution workflow - Consider third-party arbitration

Marketplace revenue comes from commissions and fees. Implementation must be precise.

Commission models:

Percentage-based: - Platform takes X% of transaction - Most common model - Easy for sellers to understand

Fixed fee: - Flat fee per transaction - Good for low-value items - Predictable for sellers

Hybrid: - Percentage + fixed minimum - Captures value at all price points - More complex to communicate

Implementation approaches:

Deduct during transfer: - Transfer €90 of €100 to seller - €10 goes to platform wallet - Clean accounting

Separate fee charge: - Transfer €100 to seller - Charge €10 fee from seller wallet - More visible to seller

Invoice-based (B2B): - Transfer full amount to seller - Invoice seller monthly for fees - Simpler cash flow for seller

Fee visibility: - Show fee breakdown before seller accepts - Include in order confirmation - Provide monthly statements - Clear reporting for tax purposes