What we do
Tools
Industries
Department
How we workLet's talk →
Home/Braintree/Braintree Marketplace
Braintree Marketplace

Braintree Marketplace After the Split: Escrow, Refunds and Seller Payouts

A customer wants their money back for a booking the seller was paid for days ago. On Braintree Marketplace, that refund is debited from your master merchant bank account, not from the seller. The product splits each sale into a service fee for you and a payout to the sub-merchant, and it can hold the funds in escrow until you release them. Keeping track of what each seller owes your platform, and when each escrowed sale should go out, is your side of the arrangement.

Before you plan around it

New platforms: Braintree's docs send merchants not already on Marketplace to Sales. There's no self-serve signup, so access is something Sales has to confirm for you.

Where: the master merchant and every sub-merchant have to be domiciled in the US, and each account needs Braintree's approval first.

What it won't run alongside: PayPal as a payment method, Braintree's recurring billing, and most third-party shopping carts.

When sellers get paid: to a checking account, 1 to 3 business days after the sale settles, unless you've held it in escrow.

One refunded sale, seen from the master merchant account

Every Marketplace transaction names the sub-merchant's merchant_account_id and a required service_fee_amount, anywhere from zero to the full sale. The fee is kept back from the seller's payout and routed to you.

Example only: a $200.00 booking with a $30.00 service fee, refunded in full after the seller was paid. The processing fee is illustrative and assumes it isn't returned.
Service fee on the $200.00 sale (The seller received the other $170.00 in their payout.) $30.00
Braintree processing fee (Taken from your side. If it's larger than the service fee, the rest comes from your settled balance.) −$6.10
Full refund to the customer (Debited from your master merchant bank account, not from the seller.) −$200.00
Your position until the seller pays back their $170.00 −$176.10

Chargebacks land the same way, with their fees on top. Holding the sale in escrow changes this: a full refund comes straight out of the held funds, so nobody has to be chased.

Escrow and disbursement surprises on a live marketplace

Escrow that stays held for weeks

How you'll know: Held transactions pile up because releasing them depends on someone in ops working through a list.

Fix: Tie the release-from-escrow call to the event that earns it in your platform, such as a delivery confirmed or a job marked complete. Braintree recommends not holding funds longer than 30 days.

A partial refund on a sale still in escrow

How you'll know: Support tries to refund part of an order and the request fails.

Fix: Escrowed funds can only be refunded in full. To refund part, release the sale first; the partial refund then comes out of your master merchant account like any other.

Releasing half an order

How you'll know: You want to pay a seller for the first stage of a job and keep the rest held.

Fix: Escrow holds and releases whole transactions, service fee included. Staged payouts need separate transactions from the start.

A payout that didn't land and nobody heard

How you'll know: A seller says they weren't paid, and your dashboard shows nothing wrong.

Fix: Banks don't confirm successful deposits. Braintree only sends a disbursement exception webhook, with codes like bank_rejected or account_not_authorized, and someone has to act on it. Venmo payouts a seller never claims send no webhook at all (see Braintree and Venmo).

Your own balance runs short

How you'll know: An insufficient_funds exception arrives about your account, not the seller's.

Fix: That code means the master merchant account couldn't cover fees, chargebacks or refunds. A refund-heavy week needs a buffer in that account.

The seller ledger Braintree leaves to the platform

Braintree tracks transactions and disbursements. It doesn't keep a balance of what each seller owes you after a refund, or tell a seller which sales made up Tuesday's deposit. n-frames builds that ledger from your Braintree data: every sale and service fee by merchant_account_id, each disbursement, and each refund or chargeback taken from your account, with what's still owed and how you've agreed to recover it.

The same build gives each seller a payout statement they can read, sends onboarding approvals and declines to your admin so a stuck seller gets help, releases escrow from your own completion event, and puts disbursement exceptions in front of a person. Deposits in your bank are matched using the MERCHANT_ACCOUNT_ID Braintree puts in the bank descriptor. It's written against the Braintree API and tested in the sandbox before it touches live money.

Sub-merchants, fees and escrow: common questions

What's the difference between Braintree Marketplace and a regular Braintree account?

A regular account takes payments for one business. Marketplace adds sub-merchant accounts under a master merchant: each sale is credited to a sub-merchant, a service fee you set is routed to you, and Braintree pays the seller's checking account directly. It's US-only, and it doesn't work with PayPal or Braintree's recurring billing.

Who handles compliance for the sub-merchants, Braintree or us?

Braintree verifies each sub-merchant's identity during onboarding and moves the money to them. Your platform still decides who to onboard, and it carries the money side: refunds and chargebacks on sales that weren't escrowed come out of your master merchant bank account, and Braintree contacts you about disputes on a seller's sales.

Does Braintree Marketplace work the same way as a payout feature for a gig or rental platform?

It's built for that shape: one customer payment, a cut for the platform, the rest paid out to an independent person or business. Escrow suits rentals and gigs well, since you can hold the money until the job's done, as long as you release within the 30 days Braintree recommends.

Does Marketplace affect how Braintree's vault or subscriptions work for the buyer?

Subscriptions, yes. Braintree lists its recurring billing as not compatible with Marketplace, so platforms that charge on a schedule run that schedule in their own code. For the vault, card verifications have to run on the master merchant account or a merchant of record, never a sub-merchant. Test any repeat charge flow in the sandbox first.

Can a new platform still sign up for Braintree Marketplace?

Not by self-serve. Braintree's docs send merchants not already on Marketplace to Sales, so availability is case by case. If you're outside the US or need PayPal at checkout, it won't fit either way, and a product like Stripe Connect or Adyen for Platforms is the comparison to make.

Who builds the reporting and escrow logic around Braintree Marketplace?

n-frames takes that on for platforms already live on it: the per-seller ledger and statements, escrow released by your own completion event, and an alert to your ops team whenever Braintree reports a payout problem.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.