eCommerce Marketplace Development: How to Handle Payment Splitting and Commission Logic

Most eCommerce marketplace briefs get this backwards. They obsess over storefront features, then treat payment splitting and commission logic like a plugin setting to sort out later. That is usually where the rework starts, because the hard part is not taking one customer payment. It is proving who owns each line item, when funds can move, how commission is recorded, and how refunds or chargebacks reverse without creating a finance mess.

Short Answer: Design marketplace payments as a controlled ledger system first, then connect the gateway, platform and payout rules around it. You need line-level order attribution, clear ownership of authorisation, capture, settlement and payout release, plus reversal logic for refunds, partial captures, failed payouts and chargebacks. If a supplier cannot explain that model clearly in plain English, your scope is not ready for build.

Most developers will tell you they have handled this before. The question is whether they have handled it correctly, or whether they have handled it well enough to get through launch. Those are very different things. The evidence is in their data model, not their portfolio – and you should be cautious regardless of how solid their eCommerce development record looks.

Why marketplace payments break when the ledger is an afterthought

A normal eCommerce checkout records one buyer payment against one merchant account and one order. A marketplace order is different: one basket can contain products from two or three vendors, each with different commission terms, payout timing and refund exposure. The moment you have two vendors in a single checkout, you have a money movement and ownership problem that no standard order management system solves cleanly out of the box.

Ask your developer how the system will record each order line, fee, commission event and payout status. If the answer starts and ends with gateway plugins, treat that as a warning sign. Most plugin vendors will tell you their tool handles commission splits. What they mean is it can apply a percentage to an order total. That is not commission logic, that is arithmetic. The commission logic is everything that happens when the percentage is wrong, when the order is partially refunded, when the payout fails, when the vendor disputes the amount.

A concrete example of where this breaks in practice: a customer buys one item from Vendor A and one from Vendor B in the same basket. Vendor A is paid weekly after delivery confirmation. Vendor B gets paid only after a 14-day returns window closes. Your platform now needs to maintain two separate hold timers, two release conditions, two payout schedules – all tied to a single customer payment transaction. If your data model only stores financial totals at order level, none of this is possible without manual intervention every time.

Here is a subtler problem that almost nobody covers in scoping: gateway settlement timing. Most payment processors operate on T+2 or T+7 settlement windows. If you have promised vendors weekly payouts but your Stripe account is on a seven-day settlement cycle, you are either fronting cash from your own working capital or your payout promise to vendors is not what you think it is. I have seen this surface in week three of a live marketplace. The vendors are already signed up, the contracts are already signed, and the answer “actually the gateway settles in seven days” is not a conversation you want to have at that point.

The hidden costs of getting this wrong are dull but expensive: payout errors, refund confusion, audit gaps, launch delays and manual workarounds in finance that never fully go away. I see this a lot in marketplace scoping – the visible brief looks tidy but the ledger logic underneath is still vague, and nobody has asked the hard questions yet.

How payment gateway architecture shapes what you can actually build

Gateway selection is not a procurement decision, it is an architectural one. Which gateway you use, and which charge model within it, determines what your commission logic can and cannot do. Stripe Connect and PayPal for Marketplaces are the two most commonly used split-payment platforms in UK marketplace builds, and each has structural implications that need to be understood before any build path is chosen.

Stripe Connect offers three charge models, and they are not interchangeable:

• Destination charges: the platform processes the customer payment and automatically routes a portion to the vendor’s connected Stripe account. The platform handles all dispute liability. This is simpler to implement but means the platform absorbs chargeback risk for every vendor transaction regardless of fault. If your vendor onboarding is light on identity verification, that exposure compounds quickly at volume.
• Direct charges: the payment processes directly against the vendor’s Stripe account. The vendor handles their own disputes. The platform collects its commission via the application_fee_amount parameter on each charge. Less operational burden for the platform, but less control over the customer experience, the statement descriptor the buyer sees, and how disputes are handled.
• Separate charges and transfers: the platform charges the customer in full, then creates independent transfer objects to each vendor with amounts and timing defined by your own application logic. This is the model you need for a proper multi-vendor order, where items belong to different vendors with different payout schedules. It is the most flexible model and the most technically demanding – it requires a reliable webhook handler for transfer.paid and transfer.failed events, your own retry logic, and reconciliation against each transfer object separately.

PayPal for Marketplaces operates through a partner referral and disbursement API with a similar split-pay pattern, but the compliance requirements for disbursing to unverified vendors are stricter and the webhook delivery behaviour differs in ways that affect how you design your failure handling. If your vendor base is international, settlement currency and conversion rates also need to be locked into the architecture before any development starts – currency selection is not a post-launch configuration.

There is a compliance dimension here that most technical briefs skip entirely. In the UK, if your platform holds vendor funds before disbursement, depending on how long you hold them and under what conditions, you may be operating as a payment institution under FCA regulation. Stripe and PayPal manage their own FCA authorisation, which is one practical reason building on their infrastructure is significantly safer than designing a custom fund-holding model without legal input. This is worth clarifying with your legal team before architecture is finalised, not after you have processed your first thousand orders.

Choose the payment flow before you choose the build path

Before you compare platforms or shortlist a multi vendor marketplace developer, decide whether funds are split at source by the payment provider or held by the platform and released later under your own rules. That choice shapes everything downstream: architecture, compliance exposure, reconciliation burden and operational flexibility.

Do not assume every platform supports both models cleanly. Not Shopify with Stripe Connect, where the charge model is constrained by the Shopify Payments integration layer and certain Stripe Connect features are unavailable on managed checkout flows. Not Magento with its payment bridge architecture, which handles gateway abstraction differently from a custom application. And not headless commerce setups, where payout logic lives entirely in your own application layer and you own every edge case the gateway does not handle for you. Headless can improve front-end flexibility; it also means you own more of the failure surface.

Decision ownership matters: define who owns authorisation, capture, settlement, payout release and reversal handling before development starts. If that ownership is vague in the scope document, it will still be vague at QA.

Where integrations are involved, the payment model also needs to line up with ERP integration, finance and reporting workflows. If you are mapping those dependencies, planning marketplace integrations before development starts will help you tighten the brief before architecture decisions harden.

Not sure if your marketplace brief covers the ledger logic properly?

Most marketplace projects underestimate payment splitting, commission tracking and payout control until the build starts. We help technical leads and founders test whether the scope is ready before architecture decisions harden.

Check your brief

Quick diagnostic call, no sales pitch, just clarity on what needs defining.

The data model that makes or breaks commission logic

I have reviewed scoping documents from a range of marketplace projects at different stages. Almost none of them include a defined PayoutEvent table. Almost all of them use the word “robust.” The two facts are not unrelated.

Commission logic cannot be reliable if the underlying data model does not support it. These are the core objects that need to exist – and be explicitly defined – before any commission engine is built:

• MarketplaceOrder: the parent order record, linked to the buyer and the transaction. Not to any single vendor. A marketplace order is a financial container spanning multiple vendor relationships, and it needs to be modelled as one.
• OrderLine: one record per product per vendor, carrying vendor_id, gross_amount, tax and shipping_cost. This is where line-level attribution starts. Without it, every downstream calculation is operating on totals rather than facts, and every reversal becomes a manual exercise.
• CommissionRule: stores the applicable rate by vendor, category, order type and effective date. This must be a database table, not a configuration file. Commission rules change, and when a vendor disputes a commission calculation from three months ago, you need the historical rule that applied on that specific date, not the current one.
• LedgerEntry: one immutable record per financial event per order line. Entry type as an enum: commission charge, vendor share, platform fee, refund, chargeback adjustment. You append to this table. You do not update existing rows. This is your financial audit trail, and it needs to be queryable by order, by vendor, by period and by event type.
• VendorBalance: running totals of pending, available and held amounts per vendor, updated by writes to LedgerEntry. Never calculate balances in real time from raw order data at query time – that will not perform under load and will produce inconsistent results during concurrent payout processing.
• PayoutEvent: one record per payout attempt, carrying triggered_at, processed_at, gateway_reference, status and failure_reason. This table is your audit trail when a vendor disputes a late or missing payment, and your operations interface when a payout fails and needs to be investigated.

If any of these objects are absent from the data model diagram in your scoping document, the commission engine is being designed by assumption. Those assumptions become bugs in production. The bugs surface after launch, when reversing them requires a database migration against live data with live vendor balances.

The PIM integration matters here too. If your product information management layer does not carry clean category and vendor assignment data through to the OrderLine record, the CommissionRule lookup breaks at the first category-based rate. That field mapping needs to be defined before development starts, not discovered when the first commission calculation is wrong.

How commission logic should be recorded so finance can trust it

Commission is rarely one flat percentage for every vendor. You may have category-based rates, promotional overrides, onboarding deals, B2B eCommerce terms, shipping exclusions or different rules for first-party versus third-party stock. The proposed build needs to store those rules at CommissionRule level, not display them in an admin config screen that has no historical accuracy and no audit trail.

The edge cases are where weak implementations get exposed:

• Bundle products spanning vendors: a gift set containing one item from Vendor A and one from Vendor B, sold as a single SKU. How does the platform split the gross amount for commission purposes at checkout? If the bundle is defined at product level in the PIM, the split logic needs to exist there too. If it is not, the commission on a bundle order is a guess.
• Mixed first-party and third-party stock: if your platform sells its own inventory alongside vendor-supplied stock, the commission rate on first-party lines is zero. The system needs to distinguish between own-stock and vendor-supplied lines at the LedgerEntry level. If that distinction is not in the data model, every finance report that touches first-party orders is wrong.
• Partial captures and partial refunds: one vendor item ships, another is cancelled. If the platform stores only order-level totals, finance has to manually calculate how much commission to reverse and against which vendor. This is the scenario that breaks the most commission implementations. It is also the most common one on any marketplace with more than a handful of vendor relationships.
• Chargeback liability allocation: who absorbs the chargeback cost – the platform or the vendor? The contract determines this, but the system needs a chargeback allocation rule that writes the correct debit to the correct VendorBalance entry. If it is not explicit in the data model, it will be explicit in a correction spreadsheet six months after launch.

Ask your developers directly: how are chargebacks posted back into the LedgerEntry, how are failed payouts marked and retried, and how are vendor balances reconciled against gateway settlement reports? If the answer describes plugin configuration rather than data model design, push harder.

If the team still has open assumptions around data ownership or commission edge cases, a structured project discovery session is cheaper than rebuilding payout logic after checkout is live.

Technical checklist: key requirements to define before project start

This is the part most teams skim because it feels less exciting than the storefront UI. It is also the part that determines whether your launch budget holds.

WEBDIGITA Marketplace Payout Checklist: Use this to test whether your brief is specific enough before discovery, vendor selection or proposal review.

• Define the gateway charge model – destination charges, direct charges or separate charges and transfers – and confirm it supports your vendor payout schedule and commission structure.
• Define when vendor payouts are released: on order, on shipment, on delivery confirmation, after a returns window, or after manual approval.
• Define the commission model at CommissionRule level: by vendor, category, order type and commercial agreement, including historical accuracy requirements for reversals and disputes.
• Define how refunds, cancellations, partial captures and chargebacks write back through the LedgerEntry table, including who bears the chargeback cost.
• Define what happens when a payout fails: failure classification, retry rules, exception queue process, vendor notification mechanism and manual review workflow.
• Define who owns daily reconciliation between gateway settlement reports, internal LedgerEntry records and the ERP or finance system, and what the process is when they do not match.
• Define vendor onboarding KYC requirements and any payout holds linked to identity verification status on the gateway.
• Define how 3PL or shipping API delivery events trigger payout release conditions in the ledger.
• Define reporting outputs – commission statements, payout histories, balance summaries, dispute logs – for finance, operations and vendors before build starts, not after launch.

Keep this checklist in the scope document, not buried in a meeting note. And if you are unsure whether the underlying data and product model can support it, it is worth assessing data readiness before marketplace logic is implemented.

What the vendor portal must handle before launch

The vendor portal is where commission disputes come to die. A vendor whose payout is two days late will email, then call, then escalate. If the portal only shows “pending” with no breakdown of why or when, your operations team becomes the explanation layer for every ambiguous status, indefinitely. That is not a support problem, it is a product design problem.

At minimum, the vendor portal needs to surface:

• Balance visibility by status: Funds pending release, funds available for payout, and funds held against open disputes. Not a single balance number – three separate states, clearly labelled, with the reason each amount is in its current state. A vendor looking at “£2,400 pending” with no context will email support. A vendor looking at “£2,400 pending – releasing after 14-day returns window on 28 June” will not.
• Payout history with gateway references: Vendors need to reconcile your payouts against their own bank statements. An internal payout ID is not enough. The gateway reference – the Stripe transfer ID, the PayPal disbursement ID – needs to be visible so vendors can match records at their end without contacting support for every discrepancy.
• Commission statements by period, to order line level: A vendor should be able to see gross sales, returns, commissions deducted and net payable for any given period without calling you. If they cannot reconcile their numbers independently, your support volume will tell you about it every month end.
• Dispute and chargeback notifications with a structured response workflow: Not just an email alias. The vendor needs to know what has been disputed, what documentation is requested and what the timeline is. If vendors find out about chargebacks through unexplained balance deductions, the relationship deteriorates fast.
• Bank account management with verification status: Vendors change banks. The portal needs a verified account update flow. The first moment you should discover a vendor’s bank details are invalid is not a failed payout webhook at 2am.

There is also a VAT dimension that applies to UK marketplace builds specifically. Under marketplace facilitator principles being applied more broadly post-Brexit, the platform can be treated as the deemed supplier for VAT purposes on certain vendor sales, depending on how the contract is structured and whether vendors are VAT-registered. That changes what the commission statement needs to display and what your finance team needs to report. This is not a question you want to answer after your first VAT return. It needs to be clarified with an accountant before the data model is finalised, because the reporting fields need to exist from the first transaction.

What secure payout operations look like after checkout

Secure payout handling is not about PCI logos on the checkout page. It is about what happens after the payment clears: holds, approvals, retries, audit trails, reconciliation under load and – critically – what the system does when something goes wrong at a time when nobody is watching.

I’ve seen this play out the same way on multiple builds. Checkout goes live, the demo looks clean, and three weeks later operations is manually adjusting payout records because nobody defined what a failed payout event means in the system – what status it sets, what reversal it triggers, who it notifies and how the retry is queued. That is a process gap dressed as a technical problem, and it compounds directly as order volume increases.

When a payout fails – and bank transfers do fail, typically in the range of 1 to 3 per cent due to invalid routing numbers, closed accounts or gateway errors – here is the sequence that needs to happen correctly:

1. The gateway fires a failure webhook (payout.failed in Stripe’s event model, equivalent events in other providers).
2. The webhook handler locates the PayoutEvent record, updates the status and reverses the VendorBalance movement that was made when the payout was queued.
3. The system classifies the failure: recoverable (invalid routing number, account not yet verified on the gateway) or terminal (account closed, vendor removed from the platform).
4. Recoverable failures enter a retry queue with configurable delay. Terminal failures go to a manual exception queue with an ops alert and a vendor notification.
5. An immutable LedgerEntry is written for the reversal, so the audit trail is complete regardless of what happens next.

If your webhook handler is not idempotent – meaning the same failure event processed twice would produce two reversals against the same VendorBalance – you now have a balance error that finance will find on reconciliation day. It is one of the quieter production bugs and one of the harder ones to explain to a vendor whose balance is wrong.

Edge cases that must reverse cleanly

Reconciliation deserves its own mention here. A daily reconciliation job should compare the gateway’s settlement report – the actual record of what moved – against your internal LedgerEntry records. Discrepancies will occur: timing differences, rounding on commission calculations at scale, transfer objects the gateway processed but your system did not receive a webhook for. The system needs a process for surfacing these discrepancies and routing them to the right queue. Silent absorption into the VendorBalance is not a reconciliation process, it is a problem accumulation process.

If you have ERP integration or finance system dependencies, confirm field mapping, export timing and journal entry logic before build starts. I’ve seen projects where checkout worked fine but financial reporting broke because settlement events, vendor balance movements and ERP journal entries were designed by different people working from different assumptions. It surfaces at the first month-end close after launch, which is precisely the wrong moment to discover it.

Performance still matters here too. Payout jobs, reconciliation runs and webhook processing must not block the buying journey or corrupt records under load. If you are evaluating platform fit, ask specifically how background job queuing, retry logic and load testing are planned – especially on plugin-heavy platforms like WooCommerce builds, where payout processing can run on the same application thread as checkout if the architecture is not explicitly designed to separate them.

If a developer cannot explain these controls specifically and clearly, the scope is still soft. That usually means the timeline and the budget are too.

Related reading: if you want the wider delivery view, read what a rigorous marketplace development process looks like and then what actually changes the cost of marketplace development.