Fund Management

Money is the lifeblood of any marketplace, and handling it correctly is critical. This page explains how funds flow from buyer payment through to seller payout, including the hold periods, fee deductions, and safety mechanisms we use.

The Money Journey

When a buyer pays for an order, the money doesn’t go directly to the seller. Instead, it follows a controlled path:

This approach protects everyone:

• Buyers can get refunds if something goes wrong
• Sellers eventually get paid for legitimate sales
• Platform can mediate disputes and detect fraud before funds leave the platform

Tracking Funds on Orders

Each order has a funds object that tracks exactly what’s happened to the money:

interface OrderFunds {
  // Concurrency control
  operationLock: 'none' | 'refund' | 'transfer'
 
  // Amounts (in cents)
  charged: number              // Original amount held
  refunded: number             // Total refunded to buyer
  transferred: number          // Total transferred to seller
 
  // Stripe references
  transferId?: string
  refundIds?: string[]
 
  // Release timing
  payoutEligibleAt?: Date      // When funds CAN be released
  paidOutAt?: Date             // When funds WERE released
 
  // Distribution breakdown
  distribution?: {
    sellerFee: number          // Platform fee deducted from seller
    buyerFee: number           // Buyer protection fee
    tax: number                // Tax withheld for remittance
    couponDiscount: number     // Platform-absorbed discount
  }
}

Fund States

Funds move through different states during the order lifecycle:

charged: 5000
refunded: 0
transferred: 0

charged: 5000
refunded: 2000  // $20 refunded
transferred: 0  // Seller hasn't received anything yet

charged: 5000
refunded: 0
transferred: 4600  // $46 after 8% fee

Release Floor

When an order transitions into a fund-releasable status (completed, resolved_partial_refund, resolved_no_refund, resolved_goodwill_refund), payoutEligibleAt is set to:

payoutEligibleAt = max(now, createdAt + 3 days)

• Order is ≥ 3 days old at the transition → payoutEligibleAt = now → next job tick releases.
• Order is < 3 days old → payoutEligibleAt = createdAt + 3 days.

The 3-day floor exists because we use platform-funded transfers (to support coupons and discounts where the transfer amount may differ from the charge amount). Unlike source-transaction-linked transfers, platform-funded transfers make funds immediately available to the seller, so we keep a short window to:

• Detect fraud patterns (e.g., self-dealing between buyer and seller accounts)
• Handle chargebacks that arrive shortly after order completion
• Intervene on suspicious coupon/discount abuse

The floor is enforced by computeReleaseEligibleAt in order.rules.ts (FUND_RELEASE_HARD_MINIMUM_DAYS = 3).

Timeline Summary

How Fund Release Works

When an order is ready for fund release, here’s what happens:

Calculating the Release Amount

The seller doesn’t get the full order amount — we deduct fees, tax, and any refunds:

releaseAmount = charged - sellerFee - buyerFee - remainingTax - refunded

Example: Normal Order

Order total:    $100.00 (subtotal: $90, shipping: $10)
Seller fee (8%): - $8.00
Refunds:        - $0.00
─────────────────────────
Release amount:  $92.00

Example: Partial Refund Dispute

Order total:    $100.00 (subtotal: $90, shipping: $10)
Seller fee (8%): - $8.00
Partial refund: - $20.00
─────────────────────────
Release amount:  $72.00

Platform-Funded Transfers

We use Stripe’s platform-funded transfer model — transfers draw from the platform’s available Stripe balance rather than being linked to a specific charge via source_transaction.

const transfer = await stripe.transfers.create({
  amount: releaseAmountCents,
  currency: order.currency,
  destination: sellerStripeAccountId,
  // No source_transaction — platform-funded
  transfer_group: transaction.id,
  metadata: {
    orderId: order.id,
    transactionId: transaction.id,
  }
})

Why platform-funded transfers? We support coupons and promotional discounts, which means the seller payout can differ from the buyer’s charge amount. With source_transaction, the transfer is capped at the charge amount. Platform-funded transfers have no such limitation.

Trade-off: Platform-funded transfers make funds immediately available to the connected account (the seller). This is why the release floor is critical — it prevents instant fund extraction in fraud scenarios on freshly-created orders.

When Can Funds Be Released?

Only certain order statuses allow fund release, and payoutEligibleAt must be in the past:

The Background Release Job

We run a scheduled job (every 5 minutes via EventBridge) that automatically releases funds when orders are ready:

The job handles:

1. Refunds for cancelled or fully-refunded orders
2. Fund releases for completed/resolved orders where payoutEligibleAt has passed

Concurrency Control

What if two processes try to release funds (or refund) at the same time? We use a Compare-And-Swap (CAS) lock:

// Try to acquire lock
const result = await OrderModel.findOneAndUpdate(
  {
    _id: orderId,
    'funds.operationLock': 'none'  // Only if no operation running
  },
  {
    $set: { 'funds.operationLock': 'transfer' }
  }
)
 
if (!result) {
  throw new Error('Another operation is in progress')
}
 
// ... do the Stripe operation ...
 
// Release lock when done
await OrderModel.updateOne(
  { _id: orderId },
  { $set: { 'funds.operationLock': 'none' } }
)

Stripe is the Source of Truth

We follow a “Stripe-first” pattern for all financial operations:

This ensures our database never says money moved when it didn’t. Stripe is always the authoritative source.

Webhook Backup

Stripe sends webhooks for financial events as a backup sync mechanism:

These are mostly for monitoring — we don’t rely on them for primary operations.

Failure Scenarios

Monitoring

Key things to watch:

Code Locations