Escrow and buyer protection for WooCommerce marketplaces

Without the add-on

With the add-on

What this add-on actually does

On an ordinary multivendor setup, the vendor's share of a sale leaves your control the moment the card clears. The buyer has paid, the vendor has been paid, and the item has not moved. If it never gets posted, you are the one apologising.

This add-on puts a gap between those two events. The buyer's card is charged as normal, but the vendor's share is held — sent on only after they mark the order shipped and a protection window of your choosing has passed. Three things then happen without you watching:

• If the vendor never ships, the buyer is refunded in full and the held payout is cancelled.
• If you refund an order, anything still held is cancelled, and anything already paid out is reversed out of the vendor's Stripe account.
• If a buyer's bank raises a chargeback, payouts on that order freeze, and if you lose the dispute the vendor's transfer is clawed back.

Is this really escrow? An honest answer

Stripe's own documentation states that Connect does not offer escrow services, on the grounds that escrow has a very specific legal definition — money held by a licensed, neutral third party who releases it when conditions are met. Nothing built on Connect meets that definition, and neither does this add-on.

What this is, precisely: a delayed, conditional payout. The buyer's money is charged into your Stripe balance and the vendor's share is not transferred until the release conditions are met. Between those moments the funds are yours — Stripe sees them that way, your bank sees them that way, and your accountant should too.

We use the word "escrow" because it is what marketplace owners search for and the behaviour they picture — the mechanism behind Vinted, Depop, eBay and OfferUp buyer protection, where the seller is paid once the buyer has had a fair chance to say something went wrong. That is genuinely useful. It is just not a legal escrow arrangement, and we would rather say so now than let you find out later.

Why a marketplace needs it

A marketplace has a trust problem a single-seller shop does not. Your buyer is not buying from you; they are buying from a stranger, on the strength of your website's reputation. When that stranger does not post the parcel, the buyer does not blame the stranger — they blame you, they charge back, and they tell people.

Holding the payout fixes the incentive at both ends. The vendor has a reason to post promptly, because the clock does not start until they do. The buyer has a window in which a problem can still be fixed with the money in reach.

Dokan Lite has no payout holding of its own — the vendor is paid however your payment stack pays them, normally straight away. On Dokan Pro, check what its vendor payment methods do before buying this; what owners find missing is not the split, it is the held window with automatic refund reversal and chargeback claw-back. Splitting a payment is easy. Getting money back out of a vendor's account three weeks later is the hard part. The comparison page covers the rest.

How it works, step by step

Follow one £35 order from checkout to payout, with the release window at its default of 7 business days.

1. The buyer pays. Checkout runs through the WooCommerce Stripe Gateway exactly as before, and the £35 lands in your Stripe balance, tagged so the vendor's transfer can be tied back to this order later.
2. The payout is recorded, not sent. On the transition to paid, BazaarKit works out each vendor's share — line items after discounts, plus tax, plus their postage, minus whatever commission Dokan reports — and writes it to the order as a held payout. No money moves, and each vendor in a basket gets their own held amount.
3. It appears in Money held, with the status Waiting on tracking — the release timer starts when the seller marks it shipped.
4. The vendor posts the item and marks it shipped from their order page in the Dokan dashboard — the only thing that starts the clock, and deliberately their own action. The protection window then runs seven business days from that moment, skipping weekends, and the status counts down: Releases in 6 days.
5. The payout releases. A job runs hourly; on the first run after the window closes it sends a Stripe Transfer of the vendor's share to their connected account, funded by the buyer's original charge rather than your general balance. The order is marked complete once every vendor on it is paid.
6. If anything goes wrong first, it does not happen. A refund cancels it, an open chargeback freezes it, and a vendor who has not finished connecting Stripe simply keeps waiting.

Only Stripe orders are held; one paid by bank transfer or on delivery passes through untouched.

What your vendors see

A banner at the top of the Dokan dashboard reads “Connect Stripe to get paid”, noting that buyers can order now but a connected account is needed before held payouts release. One click creates a Stripe Express account and sends them to Stripe's own onboarding for identity checks and bank details. Stripe holds all of it — you never see a bank account number, and no card data touches your site. Name and address are prefilled from their WooCommerce profile where it is complete, and if Stripe rejects the prefill the account is created without it, so a vendor is never blocked.

Once through, the banner becomes a quiet “Payouts active” line with a Manage payouts link into their Stripe Express dashboard. To put the same prompt elsewhere — a “Sell with us” page, say — the shortcode [bazaarkit_stripe_onboarding] renders that card on any page, showing logged-out visitors a sign-in prompt rather than a dead button.

On an order itself, a vendor sees one of three things — the part that saves you support tickets:

• Not yet shipped: a Mark as shipped button — “Starts the buyer-protection window. Your payout releases a few working days after this.”
• Shipped: “Marked as shipped. Your payout releases around 14 March.” That date uses the same window and weekday maths the payout job does, so what they are told and what happens cannot drift apart.
• Held: “Your £35.00 payout from this order is on hold”, then the actual reason — no payout account connected, or one that still needs finishing — a link to fix it, and “the money is safely held, not lost”. A generic “connect Stripe” nudge gets ignored; a named amount on a real order does not.

What buyers get

Nothing changes at checkout, which is intentional — nobody wants an extra step. What buyers get is behind the scenes, and worth saying on your own site somewhere: the seller is not paid until the item is on its way, a refund still works after the vendor has been paid, and if nothing ever ships they get their money back without asking.

That last one is deliberately generous. The buyer is made whole at the full amount they paid for that vendor's part of the order, postage included, while the claw-back on the other side only recovers the vendor's own share. If you would rather buyers raised problems during the window than waited it out, the Disputes & Resolution add-on gives them a structured way to do it, with the payout held while it is open.

Your settings, and what they change

Everything is on one screen: WordPress admin → BazaarKit → Escrow. The on/off switch sits with the other modules on BazaarKit → Add-ons.

How long should the release window be?

Long enough for the item to arrive and for a disappointed buyer to say so; short enough that vendors do not feel they are funding you. Seven business days suits domestic post; 10 to 14 is more realistic for vendors shipping abroad (see International Shipping). Changing it affects payouts not yet released, so shortening it can release a batch on the next hourly run.

What you must set up in Stripe and WooCommerce

Four things, once.

1. WooCommerce Stripe Gateway, working. Escrow rides on top of your existing Stripe checkout.
2. Connect enabled on your Stripe account, and a platform key. Creating vendor accounts is a platform-level action, so paste a platform secret key into the Escrow settings. The one field not worth skipping.
3. The Connect webhook. In Stripe, add an endpoint at https://your-site/wp-json/bazaarkit/v1/stripe/connect-webhook subscribed to account.updated, then paste its signing secret into the settings. It is how a vendor finishing their identity checks shows up straight away rather than at the next daily sync.
4. The chargeback webhook. A second endpoint at https://your-site/wp-json/bazaarkit/v1/stripe/chargeback-webhook subscribed to charge.dispute.created and charge.dispute.closed, with its own secret. Without it, a lost chargeback pulls money from your balance while the vendor keeps theirs.

Both URLs are printed on the settings screen with your domain filled in, so copy rather than type them. Each has its own secret, in separate live and test fields — which pair is used follows the Test mode setting. Every request is signature-verified, and an endpoint with no secret refuses everything.

A note on WP-Cron

The release job runs hourly and the buyer-protection job daily, both on WordPress's scheduler — which only fires when someone visits a page. If traffic is thin, point a real server cron at wp-cron.php so payouts do not drift late. Money held shows when the next run is due, and warns you if the job is not scheduled at all.

If your licence lapses

This is unusual enough to deserve its own section, because most paid plugins do the opposite. If your subscription lapses while money is still held, BazaarKit does not freeze that money. An expired card is not a reason to strand a vendor's earnings, so an unlicensed site stops taking new escrow — the only thing switched off — while every settlement path keeps running:

• Held payouts keep releasing on schedule.
• Refunds keep cancelling held money and reversing transfers, and chargebacks keep freezing and clawing back.
• Vendors can still connect Stripe — escrow held for an unconnected vendor is the money most at risk of being stranded.
• Vendors can still mark orders shipped, or the protection job would refund orders that were genuinely sent.
• The Escrow and Money held screens stay editable, so a Stripe key can still be rotated or a webhook secret re-pasted.

The Escrow screen says so rather than leaving you guessing: “This site has no active Escrow licence, so it is not taking any new escrow. Money it already holds is still being paid out, so these settings stay editable until the ledger is empty.”

Switching the module off on the Add-ons screen behaves identically — a toggle that reads like a feature switch should not quietly strand someone's earnings. Only deactivating the plugin stops settlement, and you should not do that with money still held. Once the ledger is empty the screen reverts to a locked preview: nothing to settle, nothing to break.

How to check it is working

Do this on staging with Stripe test keys, before you go anywhere near real money.

1. In BazaarKit → Escrow, paste your Stripe test platform key, set Test mode to Force test mode, and set Release after to 1 so you are not waiting a fortnight. Not 0 — that falls back to 7.
2. As a test vendor, connect a Stripe test account from the dashboard banner. Then, as a buyer, order from that vendor with a Stripe test card.
3. Open BazaarKit → Money held: the order should be listed with the vendor's amount and the status Waiting on tracking. Confirm in Stripe that nothing has been sent.
4. As the vendor, press Mark as shipped. The status changes to Releases in …, and after the window the hourly run clears the row, creates a transfer in Stripe and moves the order to Completed.
5. For the unhappy path, place a second order, let it release, then refund it by line item. Stripe should show a reversal against that transfer.

Every step writes an order note, so an order's notes are a full audit trail of what the money did and when. If you would rather poke at a working marketplace than build one, the live demo has all of this set up.

Troubleshooting

Nothing ever appears in Money held

Check the order was paid with Stripe — anything else is deliberately ignored — and that it reached a paid status, since payouts are recorded on the transition to paid, not at order creation. On a multi-vendor basket the held payouts live on the parent order, not the sub-orders. And check the module is on in BazaarKit → Add-ons: an unlicensed or switched-off site settles old escrow but takes no new.

A payout is stuck and will not release

The Status column names the reason. Waiting on tracking means the vendor never pressed Mark as shipped, so the clock never started — by far the most common. Waiting on the seller means their Stripe onboarding is unfinished; the money is safe and goes out by itself once it is done. Frozen — dispute open means a chargeback is live. If the payout reads as due but nothing happens, check the note at the top of the screen: an unscheduled release job is fixed by deactivating and reactivating the add-on.

I refunded an order and the vendor's payout was not reversed

Refund by line item, not by typing an amount into the refund box. An amount-only refund carries nothing that says which vendor it belongs to. Rather than guess — or pay the vendor in full after you refunded the buyer — BazaarKit freezes the payout on that order and leaves a note saying so. Redo the refund against the specific items and postage. Refunds touching only platform fee lines are recognised as your own money and correctly leave the vendor alone.

A vendor says their Stripe onboarding link will not open

Stripe's onboarding links are single-use and expire within minutes, so a vendor returning to an old one gets nothing. Tell them to press Connect Stripe again: every click mints a brand new link, so a fresh attempt always works. The same goes for Manage payouts.

A webhook returns 400 when I test it from Stripe

No signing secret saved, or the wrong one — usually a live secret while Test mode is forced to test, or the Connect secret pasted into the chargeback field.

Frequently asked questions

Where to go next