Payment System Introduction

Introduction to Zooly payment and revenue distribution system

Introduction

Zooly is an intellectual property marketplace where content creators (buyers) pay celebrities/talent (sellers) for the right to use their likeness in AI-generated content. The payment system handles the full lifecycle: collecting payments from buyers, distributing revenue among multiple stakeholders, accumulating shares until payout thresholds are met, and transferring funds to talent via Stripe Connect.

Currency Convention

All monetary amounts are in integer minor units, not dollars. Every variable, parameter, column, and API field that represents money must use the MinorUnit suffix to make the unit unambiguous (e.g. amountMinorUnit, platformFeeMinorUnit, totalBrandPriceMinorUnit). Never store or pass currency as floating-point dollars in the payment system.

Multi-currency support: Every table and type that holds a monetary amount also carries a currency field (ISO 4217 code, e.g. "USD", "JPY"). The system supports zero-decimal currencies (e.g. JPY, KRW) where 1 minor unit = 1 whole unit. Use the helpers in @zooly/util — minorUnitToMajor(), majorToMinorUnit(), formatMinorUnitToDisplay() — instead of hardcoding /100 or *100.

What the Payment System Does

Core Flows

Payment Collection — Charging buyers via Stripe for licenses (Voice, Image, Likeness), merch, and marketplace offers (payFor: "OFFER", escrow until delivery is accepted)
Revenue Distribution — Splitting each payment among 3 or more stakeholders: talent, platform (Zooly), Stripe fees, agents, ambassadors, host partners
Payout Accumulation — Holding earned shares in "open" tracking records until they exceed a per-user minimum threshold (default $100)
Payout Processing — Transferring accumulated funds to talent via Stripe Connect transfers
Advance Payouts — Pre-paying talent before they've earned the amount, then deducting from future earnings
Refunds — Reversing payments with negative tracking records and advance offsets
PPU (Payment Proof Url) — Generating unique PPU codes per completed transaction
Dual-Path Payment Completion — Client endpoint completes payments by verifying with Stripe API; webhook serves as a fallback

Product-Agnostic Design

The payment system is designed to be Product Agnostic. This means that the payment system doesn't know about specific products. Instead, the product details are stored in domain-specific tables.

The payment system is linked to the product via the payFor enum and the payForId foreign key.

The product details are stored in domain-specific tables.

Payment system doesn't know about specific products
Linked via payFor enum + payForId foreign key
Product details live in domain-specific tables

See Adding a New Product for more details.

Client Side - MISSING

Currently, only a server-side payment flow has been implemented. A client-side payment flow is planned to support the Product-Agnostic Design using a dedicated Stripe context provider.

Invariant

A payment consists of two linked records: a product record (product-specific) and a stripePayment record (generic Stripe payment details and status).

Creation Flow:

First, create a product record
Then, create a stripePayment record for this product
When payment completes, update the stripePayment record status to SUCCEEDED

Bidirectional Relationship:

stripePayment references the product via payForId/payFor fields
product references the stripePayment via stripePaymentId field

Amount Handling:

Payment amounts are never passed from the client to be saved in the database
The product record is the source of truth for payment amounts
Amounts are fetched from the database using getProductByPayForId() when needed

Querying Payments:

To retrieve complete payment details, always join both product and stripePayment records

Revenue Distribution Logic

Standard Payment (AI Creation — Voice, Image, Likeness)

Total Payment Amount (e.g., 10000 minor units USD = $100.00)
    |
    |-- Stripe Fee = fixed + 2.9% (fixed = 30 minor units for USD, 0 for zero-decimal currencies like JPY)
    |-- Zooly Platform Fee = fixed AI creation cost (e.g., 500 minor units = $5.00 USD)
    |-- Talent Share = total - Stripe fee - platform fee
    |
    |-- If talent has Agent: Agent gets X% of Talent share
    |
    |-- If has Host Partner: Partner gets 10% of Platform share
    |
    |-- If has Ambassadors:
    |   Each ambassador gets SAME 10% of Platform share (AMBASSADOR_SHARE = 0.1)
    |   Total deducted from platform = 10% * number_of_ambassadors

All amounts use formatMinorUnitToDisplay(amount, currency) for display, which renders the correct symbol and decimal places per currency.

Architecture Diagram

flowchart TD A[Buyer selects product] --> B[Create PaymentIntent] B --> C[Buyer pays via Stripe] C --> D["Client calls POST /complete (primary)"] D --> D2[Verify with Stripe API] D2 --> E[Complete payment & distribute shares] C --> W["Webhook charge.succeeded (fallback)"] W --> E E --> F[Create tracking records:<br/>Talent, Agent, Platform, etc.] F --> G{Accumulated >= $100?} G -->|No| H[Wait for more payments] G -->|Yes| I[Daily cron: Process payout] I --> J[Stripe Connect transfer] J --> K[Close tracking records] H --> G

Guest Users Adding a New Product

On This Page

Introduction Currency Convention What the Payment System Does Core Flows Product-Agnostic Design Client Side - MISSING Invariant Revenue Distribution Logic Standard Payment (AI Creation — Voice, Image, Likeness)Architecture Diagram