Marketplace payment architecture begins with responsibility, not an API call. The operating model must name who sells to the buyer, appears on statements and receipts, sets refund terms, handles tax and disputes, performs seller due diligence, absorbs negative balances, and reports revenue. A payment provider can implement parts of that model, but its account configuration does not replace legal, tax, accounting, or regulatory analysis in every market.
Once responsibility is settled, map one commercial transaction to payment, allocation, transfer, seller balance, platform fee, refund, dispute, reserve, and payout records. Keep these records related but distinct. The buyer's successful charge does not mean sellers have been paid, and a seller payout does not prove every underlying order is beyond refund or dispute risk.
Choose the responsibility and settlement model before integrating payments
Document seller-of-record or merchant-of-record responsibility by product, seller type, country, and payment method. Resolve contracting party, checkout disclosures, receipt issuer, statement descriptor, indirect tax, consumer rights, refunds, chargebacks, prohibited goods, seller verification, sanctions controls, and unclaimed balances. Obtain qualified advice for jurisdictions and regulated activities; do not copy another marketplace's fund flow because its licensing, seller contracts, or provider agreement may differ.
Provider terminology needs careful mapping. Stripe's current Connect configuration migration guide states that charge type affects merchant-of-record behavior and distinguishes direct from indirect charges. The onbehalf_of parameter can affect settlement merchant behavior in supported flows, but a platform must still ensure contracts, disclosures, tax, and actual operations agree. Maintain a decision record approved by legal, finance, risk, product, and engineering.
| Decision | Platform-led implication | Seller-led implication | Evidence to retain |
|---|---|---|---|
| Customer sale | Platform contracts with buyer | Seller contracts with buyer | Terms version, seller identity, checkout disclosure |
| Payment charge | Indirect charge often sits on platform | Direct charge sits on connected account | Provider account and charge type |
| Refund and dispute | Platform commonly operates and funds response | Seller may operate, subject to configuration | Case owner, evidence, debit allocation |
| Fees and revenue | Platform records gross flow and seller payable as applicable | Platform records application or service fee | Ledger policy and accounting memo |
| Loss liability | Platform reserve and capital exposure may rise | Seller bears more direct exposure | Provider settings, contract, risk decision |
Model an internal marketplace ledger independent of provider objects
Use immutable, balanced entries for buyer receivable or cash, seller payable, platform fee revenue, payment fees, tax liabilities, reserves, refunds, disputes, and payout clearing. Every entry references business event, order, seller, currency, provider object, effective time, and idempotency key. Corrections post reversing and replacement entries rather than editing history. The provider balance is evidence and a control total, not the only subledger for what the platform owes each seller.
Separate order allocation from cash movement. For a basket with two sellers, calculate item amount, discounts, shipping, tax, marketplace commission, seller fee, and rounding per seller under a versioned policy. Create payable entries only when the contracted earning event occurs: charge, acceptance, shipment, delivery, return-window expiry, or another milestone. Avoid floating-point money; preserve currency minor units, high-precision rate calculations, and deterministic residual allocation.
Select direct, destination, or separate charge and transfer flows deliberately
Direct charges suit cases where a connected seller is the transaction merchant and owns the payment relationship supported by the provider configuration. Destination charges can move a platform charge's proceeds to one connected account while retaining a platform fee. Separate charges and transfers decouple the buyer charge from one or more transfers, which supports multi-party splits or delayed seller determination but increases platform balance and reconciliation responsibility.
Stripe documents that separate charges and transfers can send funds to multiple connected accounts and that the platform balance is debited for fees, refunds, and chargebacks in that charge type. A transfer group associates records but is not a settlement guarantee. Associate every provider request with an internal transaction, use idempotency, consume webhooks with deduplication, and reconcile requested, provider-accepted, available, transferred, and paid-out states.
| Flow | Useful when | Primary exposure | Architecture consequence |
|---|---|---|---|
| Direct charge | Seller is merchant and one seller owns the order | Data and operational control distributed by account | Platform listens to connected-account events |
| Destination charge | One seller receives proceeds from a platform charge | Platform handles indirect-charge liabilities | Charge and transfer are coupled but remain separate records |
| Separate charge and transfers | One charge funds multiple parties or allocation is later | Platform liquidity, split accuracy, failed transfers | Internal ledger and transfer scheduler are essential |
| Invoice or off-session settlement | B2B or delayed collection applies | Credit, collection, mandate, and timing risk | Order and payment lifecycle must tolerate pending cash |
Control refunds, disputes, reserves, and negative balances
A refund must reverse the original economic allocation under an explicit policy: buyer amount, tax, seller payable, platform commission, shipping, and provider fee treatment. Determine whether prior transfers are reversed, future seller earnings are netted, or a reserve is debited. Never assume refunding the charge automatically reverses every transfer. Use a refund ledger transaction and idempotent provider calls, then reconcile provider status and customer communication.
Disputes have evidence deadlines and may arrive after payout. Assign ownership based on charge type and account settings. Stripe's Connect dispute guidance explains that response responsibility and debited account depend on charge and liability configuration. Preserve product description, seller identity, delivery, customer communication, return policy, authentication, and acceptance evidence. Risk rules should govern onboarding, velocity, payout delay, reserve, and exposure limits without making protected or arbitrary decisions.
Model negative balances as credit exposure. Stripe's Connect account balance documentation distinguishes pending and available balances and explains how negative-balance responsibility varies. Establish seller-level exposure, reserve availability, expected future earnings, bank-account status, dispute horizon, and concentration limits. Freeze or slow payouts by approved policy where permitted, while retaining due-process and support paths for sellers.
Schedule payouts from earned available balance and reconcile cash
A payout scheduler should consider earned balance, provider availability, reserve, refund and dispute exposure, seller verification, minimum and maximum payout, currency, bank calendar, failed-payout state, and contract. Represent payout batches and their seller-level components. A payout instruction can be pending, submitted, paid, failed, cancelled, or returned. Do not mark an invoice settled merely because the payout request was submitted.
Perform daily three-way reconciliation among internal ledger, provider balance transactions, and bank cash. Match charge, fee, transfer, refund, dispute, adjustment, payout, and foreign-exchange entries. Put unmatched items into aged queues with materiality and owner. Close accounting periods with reproducible reports, then handle later provider events as controlled subsequent adjustments. Operational dashboards should expose total customer funds, seller payables, reserves, negative balances, pending payouts, and unreconciled cash by currency.
Test fund flows with balanced scenario ledgers
Create golden scenarios for one seller, several sellers, partial capture, partial fulfillment, seller-funded discount, platform-funded discount, tax, shipping, full and partial refund, transfer reversal, dispute before and after payout, negative seller balance, failed bank payout, and currency conversion. For every step, assert balanced entries, seller available and pending balances, platform revenue, reserve, provider request, and customer amount. Replaying the same event must not add a cent.
Run close simulation with a deliberately missing webhook and a duplicated transfer event. Reconciliation should identify the missing provider transaction, deduplicate the replay, and preserve the accounting period policy when the late event arrives. Include rounding cases where a basket-level discount cannot divide evenly among seller lines. Assign the residual deterministically and reverse it using the original allocation, rather than recalculating against today's catalog or fee rules.
Marketplace payment architecture takeaways
- Decide legal, tax, customer, dispute, and loss responsibility before selecting a provider flow.
- Map provider charge types to the actual merchant and settlement model; names alone are not sufficient.
- Maintain an immutable internal ledger for seller payables, platform economics, reserves, and corrections.
- Separate payment, transfer, availability, seller earnings, and bank payout milestones.
- Reverse economic allocations explicitly for refunds and disputes instead of assuming provider automation.
- Reconcile ledger, provider, and bank every day and age every unmatched item.
Marketplace payment architecture FAQ
Is the payment provider the merchant of record?
Usually not merely because it processes a payment. Merchant-of-record responsibility follows the commercial, contractual, settlement, and regulatory arrangement. Some providers offer specific merchant-of-record products, but ordinary connected-account processing should not be described that way without confirming the service and jurisdiction.
Should sellers be paid immediately after delivery?
Delivery can be the earning milestone, but payout timing should also account for funds availability, returns, dispute horizon, reserves, seller risk, bank calendars, and contract. Delaying all sellers equally can harm good participants; use transparent risk tiers and explicit release rules.
Can provider reports replace the marketplace ledger?
They are essential reconciliation evidence but rarely encode the marketplace's complete seller contracts, allocations, reserves, tax liabilities, or adjustments. An internal balanced ledger makes obligations reproducible and supports provider migration or multi-provider routing.
Conclusion
A marketplace payment system is sound when commercial responsibility, fund movement, and accounting tell the same story. Define the responsible parties, select the charge flow that implements that model, post every economic event to a balanced ledger, constrain exposure, and reconcile through bank settlement. Those controls let payments scale without obscuring who owes whom when an order succeeds, fails, returns, or is disputed.