Marketplace Payment Architecture

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