Split Payments for Marketplaces —
Architecture Decisions That Matter

Marketplace payment architecture has a deceptively simple surface area: buyer pays, platform takes a fee, seller receives the remainder. The complexity lives in the details of when each of these events happens, what state each party's ledger shows in between, and how reversals and disputes work against a multi-party transaction.

Most teams figure this out through trial and error in production, which is expensive. This post covers the decisions that matter before you build and the traps that catch teams after they've already shipped.

The three fundamental split models

There's no universal split payment architecture, but there are three models that cover most marketplace cases.

Collect and disburse: The platform collects the full payment from the buyer, holds it, then disburses to the seller after a configurable delay. The platform's balance is the ledger of record. Seller payouts happen on a schedule (daily, weekly) or on demand. This model is simple to implement, gives the platform maximum control over timing, and makes reversals straightforward (reverse from the platform balance before disbursement). The downside: the platform is holding customer funds, which in most US states triggers money transmission licensing requirements. This is a legal question, not just an engineering one.

Pass-through split: The charge is made to the buyer, and the split to the seller is initiated atomically at authorization time. The platform receives a fee, and the seller receives their portion, both as simultaneous transfers in the payment API. This model minimizes the platform's money transmission exposure because the platform never "holds" the seller's money — it passes through instantly. The tradeoff: reversals are more complex because you have to reverse two separate transfer events rather than one.

Delayed capture split: The buyer's card is authorized immediately, but capture (and the split) is delayed until a confirmation event — typically order fulfillment, service delivery, or escrow release. This is common in service marketplaces where payment should release upon completion. The authorization hold expires after 5–7 days with most issuers, so this model only works when the confirmation window is short. For longer-duration transactions, you need either a reauthorization mechanism or a different split model.

Which model you choose determines your regulatory exposure, your reversal workflow, and how your ledger operates. Getting this wrong at the architecture level means rebuilding core payment logic rather than adjusting edge case handling.

The platform fee: percentage vs. fixed vs. hybrid

Platform fee calculation looks trivial and causes recurring bugs in practice. The issues surface when fees are calculated at different precision levels than the payment amounts.

If your fee is 3% of the transaction amount and a buyer pays $47.53, your fee is $47.53 × 0.03 = $1.4259. Round to cents and you have $1.43. The seller gets $47.53 - $1.43 = $46.10. These sum to $47.53. Good.

Now do this for 10,000 transactions with varying amounts. The cumulative rounding behavior determines whether your total disbursements to sellers match your total collections from buyers minus fees. If you always round fees up, sellers systematically receive slightly less than they expect. If you always round fees down, your fee collection is slightly short of your stated rate. Neither is a huge problem until it's audited.

Minimum fees add another edge case. If your minimum fee is $0.50 and a buyer pays $2.00 with a 3% fee rate, the calculated fee is $0.06 but the minimum applies, so the fee is $0.50. The seller gets $1.50. That's a 25% effective fee rate the seller might reasonably object to. Your fee schedule needs to define how minimum fees interact with percentage fees and your seller agreement needs to be explicit about it.

KYC for sellers: the blocking problem

Any platform collecting money on behalf of sellers and disbursing payouts is, functionally, acting as a payment intermediary. This triggers KYC requirements for the sellers (sub-merchants in PayFac parlance). You need to collect identity information, verify it, and in some cases conduct ongoing monitoring — and you cannot disburse to a seller who hasn't completed this process.

The architecture question is: what happens when a seller on your platform has completed a transaction but hasn't finished KYC? You have options: hold funds in a platform balance until KYC completes, reject the transaction entirely (bad for buyer experience), or allow the transaction and flag the seller for immediate KYC completion with a disbursement hold.

Most platforms choose the third option — allow the transaction, hold disbursement. This creates a funds-in-suspense balance that needs to be tracked and aged. If the seller never completes KYC, you need a policy for what happens to held funds. That policy needs to be in your terms of service before you launch, not after you've accumulated a suspense balance of unresolved seller onboardings.

Dispute resolution against split transactions

When a buyer disputes a split transaction, the dispute comes against the platform's merchant account (assuming the collect-and-disburse or pass-through model). If the seller has already received their portion of the funds, the platform absorbs the chargeback until recovery.

Recovery from sellers is a product policy question, not just a technical one. Do you clawback disbursed funds? Do you maintain a reserve against each seller's account? Do you have contractual recourse through your seller agreement?

The technical implementation needs to model: chargeback events that create a liability against the platform, reserve calculations per seller based on their dispute history and transaction volume, and clawback workflows that reduce future disbursements when disputes are lost. If your split payment system doesn't have a reserve model, you're implicitly taking all dispute risk onto the platform balance, which may be fine or may not be — but it should be a conscious decision.

Real-time balance vs. batched ledger

Platform ledger design — how you track what's owed to whom — determines both your operational transparency and your ability to answer support questions accurately. Two patterns exist: real-time balance updates per event, and batched ledger updates at settlement.

Real-time updates mean every authorization, capture, refund, chargeback, and fee adjustment immediately posts to the relevant ledger entries. Sellers can see their current balance and pending amounts at any moment. This is the more complex implementation but produces much better seller experience and much easier support operations.

Batched updates mean ledger entries are created in bulk during settlement runs. Simpler to implement initially, but creates a gap between "what the system shows" and "what's actually happened" that support teams spend a lot of time explaining. When something goes wrong in a settlement batch, debugging which transactions are affected requires reconstructing the batch state — much harder than examining event-level records.

For any marketplace with more than a few hundred active sellers, real-time ledger updates are worth the implementation complexity. The operational cost of running support on a batched ledger system compounds quickly with scale.

What the API layer needs to expose

Sellers on your marketplace will build their own tooling against your payment data — reconciliation exports, payout notifications, tax reporting. Your payment API needs to expose at minimum: transaction-level records with split amounts and fee amounts clearly separated, payout records that link back to the constituent transactions, dispute records with current status and timeline, and balance snapshots with a breakdown of available vs. pending vs. reserved amounts.

Platforms that treat this as an afterthought end up with sellers using manual workarounds, scraping dashboard UIs for data, and filing support tickets for information that should be available via API. The API surface for seller-side payment data is a product investment that pays off in reduced support volume and seller retention.