Capture the buyer's payment on the platform account using a PaymentIntent without a transfer — funds land in the platform balance, acting as the escrow holding account.
Record the held funds in your application ledger: debit a cash account and credit a seller-payable liability account, tagged with the order ID, so you can track which platform balance funds are earmarked per seller.
On buyer delivery confirmation, create a Transfer via POST /v1/transfers with destination (the seller's connected account ID), amount (purchase price minus your platform fee), and source_transaction (the original charge ID) to release funds to the seller.
Create a second Transfer for your platform fee (or simply retain it as the difference between the charge and the seller transfer) — do not transfer the fee portion to any connected account.
Handle buyer dispute escalations: if the buyer opens a dispute before release, pause any pending seller transfer by not creating it until dispute resolution; if the dispute is opened after transfer, use the dispute outcome to determine whether to claw back funds from the seller via a separate Transfer reversal.
Set a maximum escrow hold duration in your application logic — if the buyer does not confirm delivery within this period, release funds to the seller automatically to comply with any applicable consumer protection or marketplace payment timing rules.
Known gotchas
Stripe does not natively enforce escrow — you implement it in your application by controlling when you create Transfers; if your application fails or crashes after capturing but before creating the Transfer, you must have a reconciliation job that detects uncaptured platform-balance funds and releases them appropriately.
Stripe's source_transaction parameter on a Transfer requires the funds from that specific charge to have settled — for card charges this is typically within 2 business days; attempting the Transfer before settlement will fail with an insufficient funds error even if your aggregate platform balance is positive.
Reversing a Transfer (clawback) debits the connected account's Stripe balance; if the connected account has already paid out those funds to their bank, the connected account balance goes negative and Stripe will seek to recover it — set expectations with sellers about potential clawbacks in your marketplace Terms.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?