How to Design a Dispute and Refund Flow for a Marketplace

Designing a dispute and refund flow for a service marketplace comes down to four decisions you make before launch: who holds the money while a job is in progress, what evidence each side must submit, who rules on the outcome, and how funds travel back. Settle those and the rest is configuration and a stated clock. Skip them and every disagreement becomes a manual email thread that ends with someone feeling cheated.

Who should hold the money while a service is being delivered?

The party that can reverse a payment without asking permission should hold it. Escrow, where the platform or its payment provider holds funds until the buyer accepts the work, gives you that power. Charging the seller directly does not.

Escrow is a payment arrangement in which an intermediary holds funds and releases them only when agreed conditions are met. In a marketplace, that condition is usually the buyer confirming completion, or a timer expiring without a complaint. Refund design is really a question of control: if the money sits with the seller, a refund is a request. If it sits with you, a refund is a state change you can execute.

Three models dominate, and the one you pick sets the difficulty of everything downstream.

Authorization means a bank sets money aside on a card without moving it. Capture means the money actually moves. Authorization windows are short, often around 7 days, which is why long service jobs usually need a deposit plus balance structure, or a payment provider that supports extended holds.

What are the stages of a dispute and refund flow?

A workable flow has six stages: a filing window, evidence collection, triage, a decision, the money action, and closure with a reason code. Each stage needs a named owner and a stated clock, or disputes stall between them.

1. Filing window. The buyer can open a dispute from job completion up to a fixed deadline, typically 3 to 14 days depending on category. After that, release happens automatically.
2. Evidence capture. Both sides submit through a form with fixed fields rather than by email: photos, timestamps, message history, and a short written statement. Structured fields are what make later review possible.
3. Triage. An operations reviewer checks whether the claim is complete and whether an existing rule can settle it. Most teams resolve roughly 60% to 80% of claims at this point.
4. Decision. A stated rule or a named person assigns an outcome: full refund, partial refund, release to seller, or split. Each outcome carries a reason code that feeds reporting.
5. Money action. The refund or release executes against the payment ledger. A ledger is an append-only record of every movement of money, and it is the only reliable source of truth when the provider dashboard disagrees with yours.
6. Closure and appeal. Both parties receive the outcome and a short window, often 48 to 72 hours, to appeal once. One appeal maximum keeps the queue bounded.

Two engineering details make or break this. The first is a state machine, which is a fixed list of statuses such as filed, evidence pending, under review, decided, and closed, with defined allowed transitions between them. Without one you get records in impossible states, like refunded and awaiting seller response at the same time. The second is idempotency, which means running the same refund instruction twice produces one refund rather than two. Payment retries and webhook replays are normal, so every money action needs a unique key attached to it.

If you are building the platform itself alongside this, the dispute flow belongs in the same build rather than bolted on later, which is the usual shape of marketplace platform work.

How long should each stage be allowed to run?

Give every stage a default clock and an escalation path: filing windows of 3 to 14 days, evidence collection of 48 to 72 hours, and a first decision within 3 business days. Anything longer trains users to escalate publicly.

The clocks matter more than the rules. A dispute resolved in four days with an imperfect outcome usually damages trust less than one resolved in three weeks with the correct answer. Publish the windows in the checkout flow and the confirmation email, not in a help article nobody opens.

Two operational choices sit behind the clocks:

• Who decides. Small teams use trained support staff working from a scoring rubric. Larger ones add a specialist queue for claims above a value threshold, often around $500 or 5% of average order value.
• What gets approved automatically. Claims under a small threshold, typically $20 to $50, are often cheaper to refund than to review. Work out the fully loaded cost of one manual review, usually 10 to 20 minutes of staff time, and set the threshold just below it.

How do you handle chargebacks and card reversals?

Assume some buyers go to their bank instead of your flow, so design for it. A chargeback is a cardholder asking their bank to reverse a charge. You cannot stop it, but you can make the reversal winnable.

• Put the chargeback reason code, the amount, and the linked job on a single dispute record, so the money view and the service view agree.
• Freeze the seller payout for the disputed amount while the reversal is open. Releasing funds and then losing the reversal creates a negative seller balance that is hard to collect from a small seller.
• Keep an evidence pack per job: acceptance timestamp, completion photos, message log, and delivery confirmation. Banks often give you 7 to 14 days to respond, and a pack that exists on day one wins more often than one assembled under deadline.
• Track chargebacks separately from platform disputes. A rising chargeback rate, above roughly 0.5% to 1% of transactions, is a product signal about unclear pricing or slow delivery, not only a payments problem.

What should you measure once the flow is live?

Track four numbers weekly: dispute rate per 100 jobs, share resolved at triage, median time from filing to payout, and refunds as a share of transaction value. They tell you whether the product or the operations team is the problem.

Outcome reason codes are short fixed labels such as not as described or no-show, and they should stay stable over time. They are how you discover that one category, or one cohort of sellers, generates most of the disputes. Gross merchandise value, usually shortened to GMV, is the total value of transactions flowing through the marketplace before your commission, and refunds as a share of GMV is the figure finance will ask about. Review the thresholds quarterly. A rule that made sense at 200 jobs a month is often the wrong rule at 20,000.