Marketplace Payment Flows: Buyer to Seller and Refunds

Map the obligation, provider balance and bank movement#

A marketplace payment flow connects the buyer’s purchase, the seller’s entitlement, the platform’s fee and the provider’s movement of funds. Build the map around those separate records. A successful charge is not a seller bank deposit, and a transfer to a connected account is not a payout to its external bank account.

This guide uses documented Stripe Connect charge models as concrete examples, checked on 3 October 2026. The accounting figures below are illustrative assumptions, not provider prices or a determination of your legal or accounting role. The chosen model must also fit the platform’s countries, seller account configuration, contracts and approved business activity.

Write the commercial agreement before choosing an API#

An API field does not settle these legal questions. For example, on_behalf_of affects Stripe’s settlement merchant behavior, such as statement and settlement details. It is not a substitute for assessing who contracts with the buyer or whether the platform acts as principal or agent for revenue recognition.

Choose a charge model with its liability attached#

The Connect charge-model documentation describes these distinctions. Use direct charges only where the account and commercial setup fit; use destination charges for an eligible charge with a known destination; consider separate charges and transfers when allocation or timing needs to be decoupled. None is a universal winner.

Confirm the exact cross-border and currency support for the proposed model. A provider operating in two countries does not establish that every transfer between those countries is supported. Seller onboarding completion, enabled capabilities and available balances must be checked before releasing funds.

Draw the money movement as distinct stages#

• Buyer obligation: order, amount, currency, seller allocation and delivery terms.
• Payment attempt: provider account, payment reference, authorization/capture state and outcome.
• Provider balance: gross charge, fees, refunds and available versus pending funds.
• Seller allocation: entitlement, adjustments and any reserve or release condition.
• Transfer: movement between platform and connected provider balances.
• Payout: movement from the relevant provider balance to the external bank account.
• Bank reconciliation: confirmation that the expected deposit or debit reached the bank.

Keep the order ID, payment ID, transfer ID and payout ID linked without treating them as interchangeable. One order can have multiple payment attempts; one payment can fund several allocations; a bank payout can aggregate many transactions. A joined report should explain those relationships instead of assuming a one-to-one match.

Work a $100 sale through the ledger#

Assume a completed sale of $100, no tax, a $90 seller entitlement, a $10 platform commission and a hypothetical $3 processing fee borne by the platform. Assume the platform is an agent under its accounting assessment and has earned the commission at this point. These assumptions determine the entries; another contract or recognition timing requires different entries.

After the fee, the platform’s provider balance is $97. After the $90 transfer, it is $7, while the seller has $90 in its connected balance. Gross marketplace volume is $100; the assumed platform revenue is $10, with $3 of processing expense. Reporting all $100 as platform revenue would contradict the agent assumption.

The transfer entry assumes the contract treats a confirmed credit to the seller’s connected balance as settlement of the seller payable. If settlement instead requires an external bank deposit, retain an appropriate transit obligation until that event is confirmed. The seller’s later bank payout remains a distinct operational state in either case.

Calculate the cash needed for a full refund#

Before transferring to the seller, a full $100 refund in this example reverses the $90 seller payable and $10 commission. If the original $3 fee is not returned, the provider balance contains only $97, so the platform needs another $3 of available funding. Do not assume the refund request returns the fee or succeeds immediately.

Stripe’s refund guidance says original processing fees are not returned. Refunds use available balance; an underfunded card refund can remain pending, while refunds for other method types fail in the described condition. The charge model determines which account is debited.

A refund after payout creates a recovery problem#

Now assume the seller has already received its $90 at the bank. The platform has $7 remaining. Its agreement requires the seller to reimburse $90 if this sale is refunded, and the platform reverses its $10 commission. Record a seller receivable of $90 and a $10 commission reversal against a $100 buyer refund obligation. The receivable is a claim, not available cash.

A $100 refund therefore needs $93 of additional funding if the platform’s only available balance is $7 and no seller recovery has arrived. Successful recovery of $90 later leaves the platform bearing the original $3 processing cost. If the $90 cannot be recovered, the platform also faces that credit loss; a contract alone does not finance the refund.

For destination or separate-charge flows, returning money to the buyer does not by itself recover the seller’s funds. The transfer-reversal API supports full or partial reversals up to the remaining unreversed amount. Confirm whether reversal is permitted and funded in the actual configuration. A completed bank payout can make recovery materially harder.

Track refund approval, provider submission, pending or failed outcome, seller recovery and any impairment separately. Do not promise the buyer a completed refund solely because a request was submitted. If a dispute is already open, resolve the provider’s supported route before initiating an additional refund that could duplicate reimbursement.

Use reserves and release conditions deliberately#

A reserve should match observed exposure: unfulfilled orders, late refunds, disputes, seller concentration and the interval between seller release and potential buyer claims. Document the amount or rule, owner, release conditions and contractual authority. Avoid a blanket percentage presented as sufficient for every marketplace.

Stripe’s manual-payout documentation explicitly says Stripe does not provide escrow services or support escrow accounts. Delaying a payout is not automatically escrow. Holding periods and capabilities vary by country and setup; confirm the current rule for each seller rather than applying one global deadline.

Keep business state and delivery state separate#

A timeout is an unknown outcome, not proof of failure. Retrieve the original provider object or retry the same operation with the appropriate idempotency key before attempting a new charge or transfer. Stripe’s idempotency documentation explains request-level protection; your database must also prevent repeated business effects across different requests and events.

For webhooks, verify the signature and capture the event in durable storage or a durable queue before acknowledging it. If capture fails, return a failure so delivery can be retried. Workers should deduplicate deliveries, check current provider state when events arrive out of order and apply ledger and allocation effects atomically or through a recoverable outbox.

Reconcile the complete flow, including exceptions#

• Match gross captures and refunds to the provider’s balance transactions.
• Explain fees, adjustments, reserves and currency conversions separately.
• Match transfers to seller allocations and reversals to the original transfers.
• Match aggregated payouts to bank deposits without marking every constituent order as a separate bank payment.
• Assign owners to pending refunds, failed payouts, unresolved attempts and unrecovered seller balances.
• Check totals by currency; convert for reporting under the accounting policy, not by adding unlike currencies.

For a hypothetical batch of ten $100 sales under the same assumptions, gross volume is $1,000, seller entitlements are $900, commission is $100 and processing expense is $30. Before seller transfers, net provider funds are $970; after $900 of transfers, the platform retains $70. Any discrepancy needs a named fee, adjustment or unresolved transaction, not a balancing entry with no source.

Release with evidence from both ordinary and adverse flows#

Before widening the flow, verify a successful purchase, delayed result, partial allocation, duplicate event, failed payout, refund before transfer and refund after seller release. Include a timeout with an eventual success so recovery does not create a second charge. Record what happened to buyer obligations, seller balances, platform cash and accounting entries in each case.

Measure paid obligations rather than counting webhook deliveries or transfer attempts as sales. Report the age and amount of unresolved payments and recoveries. A high payout success rate does not establish that the platform has enough cash to refund buyers after sellers have withdrawn.