Payment System Overview

PreviousNext

Overview of Zooly payment and revenue distribution system

What is the Payment System?

The Payment System is a multi-party revenue distribution platform that handles the full lifecycle of payments in the Zooly marketplace. It manages payments from buyers, distributes revenue among multiple stakeholders (talent, agents, platform, Stripe fees, ambassadors, host partners), and processes payouts to talent accounts.

Key Features

  • Stripe Integration: Secure payment processing via Stripe PaymentIntents and Stripe Connect
  • Multi-Party Revenue Splits: Automatically distributes payments among 3-7 stakeholders per transaction
  • Payout Automation: Daily cron job processes payouts when accounts reach $100 threshold
  • Advance Payouts: Pre-pay talent before earnings accumulate (with automatic offset)
  • Refund Handling: Full refund support with automatic reversal of revenue distributions
  • Audit Trail: Comprehensive logging of all payment operations
  • Dual-Path Completion: Client endpoint completes payments by verifying with Stripe API; webhook serves as a fallback

System Components

1. Payment Processing Pipeline

Creates Stripe PaymentIntents by fetching product data (source of truth for price and seller), and tracks checkout state from initiation through completion.

2. Payment Completion Engine

Atomically marks intents as completed, creates payment records, and generates share tracking records for all stakeholders.

3. Revenue Distribution System

Splits each payment among stakeholders:

  • Talent: Content creator/seller (primary recipient)
  • Agent: Talent's representative (optional, deducted from talent share)
  • Platform: Zooly platform fee
  • Stripe Fees: Transaction processing fees
  • Host Partner: Embedding partner (10% of platform fee)
  • Ambassador: Referral partner (optional)

4. Payout Accumulation & Processing

Holds earned shares until threshold ($100 default), then transfers via Stripe Connect to talent accounts.

5. Advance Payout Mechanism

Pre-pays talent and automatically offsets against future earnings.

6. Refund Reversal Engine

Creates negative records, cancels originals, and adjusts advance balances when refunds occur.

7. Dual-Path Payment Completion

The client endpoint (POST /api/payments/complete) actively completes payments by querying the Stripe API to verify charge status, then calling the completion engine. The Stripe webhook (charge.succeeded) serves as a fallback for cases where the client never calls the endpoint (e.g., user closes the browser). Both paths call the same idempotent completePayment() function with FOR UPDATE row locking, so only one succeeds.

8. Audit Logging

Structured payment event logging with component tagging for debugging and compliance.

Currency Convention

Architecture Highlights

  • Account-Centric: All payments keyed by accountId (not userId)
  • Atomic Operations: Critical paths use database transactions to prevent inconsistencies
  • Idempotent Webhooks: Handles duplicate Stripe webhook events safely
  • Two-Phase Payouts: DB record creation → Stripe transfer → confirmation pattern prevents double-payouts
  • System Accounts: Uses dedicated accounts (zooly_acc, stripe_acc) for platform and fee tracking

Payment Lifecycle

Checkout Initiation → Payment Intent Created → Stripe Processing → 
Client Completes (or Webhook Fallback) → Payment Completed → Share Tracking Created → 
Payout Accumulation → Threshold Reached → Payout Processed

Next Steps