Marketplace Seller Payout System Development

Development of Seller Payout System for Marketplace

A payout system is what makes a marketplace trusted by sellers. Payment delays, non-transparent deductions, or calculation errors quickly lead to vendor churn. At the same time, the payout system carries financial and legal risks: must account for holds, escrow, refunds, commissions, tax documents.

Financial Model

Customer money arrives at the platform's account. Platform retains commission and periodically transfers net amount to seller. Key entities:

seller_balances (
  seller_id, available_balance, hold_balance, total_earned,
  currency, updated_at
)

balance_transactions (
  id, seller_id, type, amount, balance_before, balance_after,
  reference_type, reference_id,
  status, created_at, description
)
-- type: order_credit | commission_debit | payout_debit | refund_debit | adjustment

Money Lifecycle

1. Order paid → amount minus commission credited to seller's hold_balance
2. Hold period expires (typically 7–14 days after delivery) → transfer from hold to available
3. Seller requests payout → create payout_request
4. Platform approves and initiates transfer → status processing
5. Transfer confirmed by bank → status completed, debit from available_balance

Hold protects against situations where seller withdraws money and buyer initiates chargeback.

Payout Schedule

Marketplaces use different models:

• On demand — seller initiates withdrawal anytime (minimum amount threshold)
• Scheduled — automatically every week/two weeks/month
• Hybrid — planned + on-demand by request

For automatic payouts: scheduled job runs at fixed time, selects sellers with available_balance ≥ min_payout, creates batch payout.

Payment System Integration

Payouts implemented via:

• YuKassa Split / YuMoney — for RF marketplaces
• Tinkoff Partners / Sberbank Business — bank transfers
• Stripe Connect — for international marketplaces
• PayPal MassPay — mass payments to foreign countries
• Direct bank transfers via bank API or XML files for bank client upload

Each provider has own confirmation format and webhook notifications for success/failure.

Refund Processing

Refund reduces seller balance. If sufficient funds in account — deducted from available_balance. If insufficient — from hold_balance, if neither exists — negative balance forms, blocking future payouts until repaid.

On refund:
1. Refund to buyer → from escrow/platform balance
2. Debit seller: refund_amount + commission return (optional)
3. Record in balance_transactions with type='refund_debit'

Documentation

In RF, sellers need:

• Act of performed work / agent report for period
• Invoice (for VAT payers)
• Sales register for tax declaration

Documents generated automatically: PDF via wkhtmltopdf or Puppeteer, saved to S3, available in seller account. Different templates for individual entrepreneurs and self-employed.

Seller Interface

• Current balance: available / on hold
• Transaction history with filters and Excel export
• Payout request form: amount, details (pre-linked)
• Current payout status: processing / completed / failed
• Document archive by periods

Details Verification

Before first payout — mandatory verification of bank details: IBAN/account number, bank BIC (check against Bank of Russia directory), compliance with INN. Some platforms require test transfer of 1 ruble with confirmation.

Financial Control

• Limits: daily and single withdrawal limits (protection from account compromise)
• Double confirmation for large payouts (above threshold value)
• Anomaly monitoring: sharp payout increase, unusual details
• Reconciliation: daily verification of payout amount with payment system

Development timeline: 6–8 weeks for complete system with automatic payouts, documentation, and payment system integration.