Marketplace Payments Are Harder Than You Think

If you're building a marketplace, you've probably budgeted a week or two for "payments." After all, Stripe makes it easy, right? Drop in some code, money flows through, job done.

I've got bad news.

Payments in a two-sided marketplace are nothing like payments in a normal app. The technical integration is the easy part. The business logic — the decisions about who gets paid what, when, and what happens when things go wrong — is where it gets genuinely hard.

I built TidyLinker's entire payment infrastructure using Stripe Connect. Here's everything that was more complicated than expected.

The Basic Problem

In a normal e-commerce app, money flows in one direction: customer pays, you receive. Simple. One Stripe Checkout session, one bank account, done.

In a marketplace, money flows in at least three directions:

1. Customer pays into the platform
2. Platform takes its fee
3. Service provider gets their cut

Already more complex. Now add:

1. What if there are multiple service providers on one booking?
2. What if the customer wants a refund after partial completion?
3. What if the service provider hasn't completed KYC verification yet?
4. What about tax on the platform fee?

Each of these is a decision tree, not a code snippet.

KYC: The Conversion Killer Nobody Warns You About

Before a service provider can receive money through your platform, they need to be verified. Know Your Customer regulations require identity verification, proof of address, and in some cases business registration documents.

Stripe Connect handles the verification process, which is good. What it doesn't handle is the user experience problem.

You've got a cleaner who just signed up to your platform, excited to start earning. And the first thing they hit is: "Upload your passport, proof of address, and bank details." Many of them bounce immediately. Others start the process, get confused by the document requirements, and abandon.

On TidyLinker, we had to build an entire onboarding flow around this. Not just the Stripe bits — the user guidance, the status tracking, the email nudges when verification stalls, the admin dashboard for reviewing and resolving verification issues.

The decisions you need to make:

• Do you let providers accept jobs before verification is complete? If yes, what happens to the money? If no, you lose providers who get frustrated waiting.
• How do you communicate verification status? The provider needs to know what's happening. Stripe's default status messages aren't user-friendly.
• What happens when verification fails? Expired ID? Address mismatch? You need a human workflow for this, not just an error message.

We chose to let cleaners set up their profiles and receive quotes before verification was complete, but require verification before they could accept a booking with payment. This balanced conversion against compliance. But it added significant complexity to the booking flow — you need conditional logic throughout.

Payout Timing: When Does the Provider Get Paid?

This sounds simple until you think about it for five minutes.

Immediately after payment? The customer pays, the provider gets their money straight away. Problem: what if the service hasn't been delivered yet? What if there's a dispute? You've already released the funds.

After service completion? More sensible. But who confirms completion? The provider? The customer? What if they disagree? What's the timeout before auto-completion?

Delayed by X days? A holding period gives time for disputes. But providers waiting days for their money creates friction and cash flow problems.

For TidyLinker, we use an authorize-then-capture flow. When a client books a cleaner, the payment is authorised (funds are held on their card) but not captured. The money only moves when the job is confirmed as complete. This gives us a window for disputes without holding the provider's money indefinitely.

But even this creates edge cases:

• Authorization expires after 7 days. What if the cleaning job is booked for next month?
• What if the client's card is declined at capture time, even though authorization succeeded?
• What about tips or additional charges after the initial booking?

Every one of these is a business decision with technical implications. And every one was a conversation between me and Adele before I wrote any code.

Refund Flows: Where It Gets Properly Messy

Customer wants a refund. Seems simple. It's not.

Scenario 1: Full refund, service not delivered. Relatively straightforward. Refund the full amount. But who eats the Stripe processing fee? The platform? The provider? The customer still paid it, even if it's invisible to them.

Scenario 2: Partial refund, service partially delivered. The cleaner did 2 hours of a 4-hour job and the client wasn't happy with the quality. Do you refund 50%? Who decides? Does the cleaner still get paid for the 2 hours? Does the platform still take its fee on the reduced amount?

Scenario 3: Dispute/chargeback. The customer goes directly to their bank instead of requesting a refund through your platform. Now Stripe freezes the funds, charges you a £15 dispute fee, and you have to provide evidence that the service was delivered. If you lose, the money comes from the platform's account.

Scenario 4: Refund after payout. You've already paid the provider. Now the customer wants a refund. Do you claw the money back from the provider's account? Can you even do that? What if their balance is zero?

For TidyLinker, we built a dispute resolution workflow: client raises an issue, both parties can respond, an admin reviews and decides. If a refund is warranted, we determine the split. This is more operational overhead than most founders expect, but it's essential. Letting Stripe handle disputes automatically means you lose control of the customer experience and almost certainly lose the dispute.

Platform Fee Splits: The Arithmetic of Greed

How much does the platform take? This isn't just a business decision — it's a technical architecture decision.

Percentage-based fees (e.g., 15% of each transaction) are the most common. Simple to calculate, scales with transaction value. But it means you need to compute the split on every transaction and handle rounding correctly. A 1p rounding error multiplied by thousands of transactions adds up.

Fixed fees (e.g., £2 per transaction) are simpler technically but don't scale with value. A £2 fee on a £200 cleaning job is reasonable. On a £20 job, it's 10%.

Tiered fees (different percentages at different volumes) are a retention tool — reward your best providers with lower fees. But they're complex to implement because you need to track volume and update fee calculations dynamically.

Stripe Connect supports all of these models, but you need to tell it exactly how to split each payment. That means your application needs to calculate the split, apply the correct fee structure, handle rounding, and do it all correctly every time.

And then there's VAT. If your platform charges a fee for a service, that fee is likely subject to VAT. The cleaning service itself might be zero-rated or standard-rated depending on what it is. You need to get this right because HMRC does not have a sense of humour about payment processing errors.

What Stripe Connect Actually Gives You

Credit where it's due: Stripe Connect handles an enormous amount of complexity. KYC verification, bank payouts, refund processing, dispute management, tax reporting for US providers (1099s), and dashboard access for your connected accounts.

But Stripe Connect is a toolkit, not a solution. It gives you the building blocks. You still need to:

1. Design the payment flow for your specific marketplace
2. Make all the business decisions about timing, fees, and disputes
3. Build the UI for provider onboarding and payment status
4. Handle all the edge cases specific to your domain
5. Build operational tools for your team to manage payment issues

On TidyLinker, the Stripe integration took about three weeks. Not three weeks of writing Stripe code — three weeks of building the complete payment experience including the business logic, edge case handling, admin tools, and testing.

The Decisions You Need To Make Before Writing Code

If you're building a marketplace, sit down and answer these before your developer writes a line of payment code:

1. When does the provider get paid? Immediately? After completion? After a review period?
2. What's your platform fee? Percentage? Fixed? Tiered? Who pays the Stripe processing fee on top?
3. How do refunds work? Full only? Partial? Who decides? What's the process?
4. What happens with disputes? Do you mediate? Auto-refund? Require evidence?
5. What's the provider onboarding flow? When do you require KYC? What happens while it's pending?
6. How do you handle failed payouts? Provider's bank details wrong? Account closed?
7. What about cross-border payments? Do you operate in multiple currencies? Multiple countries?

If you can't answer these clearly, you're not ready to build payments. And if your developer starts building payments without asking you these questions, that's a red flag.

Marketplace payments aren't a feature. They're the operational backbone of your business. Treat them accordingly.

---

If any of this resonates, I work with founders directly — from early MVP planning through to scaling. No fluff, just practical engineering.