Building marketplaces: payments, trust and payouts

By Marco Lopes · Published July 24, 2024 · Topic: Web Development

A marketplace is not just a catalogue with a checkout button. We are coordinating relationships between buyers, sellers, payment providers and our own operations team. Each relationship brings different expectations about who gets paid, when money moves and what happens when something goes wrong.

At Kordspace, we work as a remote collaborative software, AI, Web3, hardware and design studio. When we build marketplaces, we treat payments and trust as product architecture, not integrations to bolt on before launch.

Our starting point is simple: we need to explain every payment, every balance and every payout. If we cannot explain them clearly to a seller or support teammate, we probably have more design work to do.

Start with the commercial model

Before choosing a payment API, we map the transaction. Who sells the product or service? Who contracts with the buyer? Who handles taxes, refunds and complaints? What fee does the platform earn, and when is that fee considered earned?

We document whether we are building a goods marketplace, a services platform, a booking system or another model. A physical shipment and a completed consulting session need different evidence, cancellation rules and payout timing.

We also identify the seller of record and any merchant-of-record arrangement. Those responsibilities depend on contracts, provider configuration and applicable law; we do not assume that using a marketplace payment product transfers them automatically.

Our first deliverable is usually a transaction diagram and a responsibility table. We review these with the payment provider and appropriate legal and accounting advisers before implementation. This is cheaper than discovering that our checkout contradicts our operating model.

Choose payment infrastructure around money movement

We generally prefer established marketplace payment infrastructure, such as Stripe Connect or Adyen for Platforms, over collecting money into an ordinary business account and manually forwarding it to sellers. Availability and capabilities vary by country, business category and integration model.

We evaluate providers against real requirements:

• Supported platform, seller and buyer countries.
• Identity verification and business onboarding.
• Charge, transfer and payout options.
• Refund, dispute and negative-balance responsibility.
• Payment methods, currencies and settlement timing.
• Reporting, reconciliation and support access.

We distinguish three events that product teams often collapse into one: charging the buyer, allocating or transferring funds to a seller account, and paying funds out to the seller’s bank. They can happen at different times and fail independently.

We avoid promising “escrow” unless the legal and provider arrangements genuinely support it. Delaying a transfer or payout does not, by itself, create an escrow service.

Model checkout as a workflow

A browser redirect is not proof that a payment succeeded. Buyers close tabs, authentication takes time, networks fail and some payment methods confirm asynchronously.

We model orders and payments separately. An order might move through draft, awaiting_payment, confirmed, fulfilled and cancelled. A payment has its own lifecycle, including pending authentication, processing, success, failure and refunds. We define valid transitions instead of relying on a single paid flag.

For inventory or bookings, we specify reservation expiry and the response to late payment confirmation. Otherwise, we can accept money for something that is no longer available.

We calculate prices, fees and seller allocations on the server. The browser submits selections, not authoritative totals. We snapshot the agreed amounts and relevant policy versions so later catalogue changes cannot rewrite an existing order.

We also decide whether a multi-seller basket is necessary at launch. Separate seller orders are often easier to fulfil, refund and reconcile.

Make seller onboarding part of the product

Seller onboarding is a conversion flow, but it is also a compliance and risk boundary. We prefer provider-hosted or embedded verification components where appropriate, reducing the sensitive identity information our application handles directly.

We represent onboarding as explicit states: not started, information required, under review, enabled and restricted. More importantly, we track capabilities individually. A seller may be able to publish listings while remaining unable to accept payments or receive payouts.

Our interface explains what is missing, what the seller can do next and whether an external review is pending. We avoid promising approval dates we do not control.

Verification is not permanently finished after signup. Requirements can change, documents can expire and accounts can become restricted. We process provider updates and surface actionable notices.

We also protect payout-account changes with stronger authentication, notifications and, where appropriate, review or a cooling-off period. A compromised seller account should not make earnings easy to redirect.

Keep a ledger, not just a balance column

A marketplace needs an internal record of financial obligations. The payment provider records activity in its system; our application must explain how that activity relates to orders, sellers, fees and adjustments.

We favour an append-only, double-entry ledger for financial events. Each transaction contains balanced entries, with clearly defined account meanings. Corrections use reversing or adjusting entries rather than silently editing history.

We store amounts as integers in each currency’s minor unit, using currency-aware rules. We never use floating-point arithmetic for money or assume every currency has two decimal places. We record currency explicitly and keep conversion events separate.

For a purchase, we need to account for the gross amount, platform revenue, seller obligation and relevant processing costs. Refunds and disputes must reference the original transaction without erasing it.

Balances can be derived and cached for performance, but their source remains auditable entries. Our ledger supports product operations; we still align exports and accounting treatment with qualified advisers.

Design webhooks for retries and disorder

Payment webhooks are distributed-system messages. We assume duplicates, delays and out-of-order delivery rather than treating them as exceptional bugs.

Our handler verifies the provider signature against the raw request body, records the event durably and acknowledges it promptly. We then process work asynchronously. Each event has a uniqueness constraint, and each business action has an idempotency rule.

These are different protections. Deduplicating an event does not prevent two different events from attempting the same transfer. We give the transfer operation its own stable identifier and use provider idempotency keys where supported.

We do not allow an older event to regress a newer state. When necessary, we retrieve the provider’s current object and apply permitted transitions.

We also run reconciliation jobs. These compare provider transactions and balances against our records, flag discrepancies and give operations a repair path. Webhooks provide timely updates; reconciliation catches missing or inconsistent ones. Both belong in the initial architecture, not a future reliability backlog.

Treat payouts as a controlled promise

“Available balance” must mean something precise. We distinguish pending earnings, available earnings, amounts reserved for risk and payouts already in progress. We also show the difference between a payout being initiated and money arriving at a bank.

We choose payout timing based on fulfilment, refund exposure, provider capabilities and contractual commitments. New sellers or higher-risk categories may warrant different schedules, provided those policies are lawful, disclosed and supported operationally.

Before releasing funds, we check that the seller remains eligible, the relevant earnings are available and no blocking review applies. We use transactional updates or locking to prevent concurrent workers from paying the same balance twice.

We prepare for failed payouts and negative balances. Who covers a refund after the seller has already been paid? Can funds be recovered, offset against future earnings or absorbed by the platform? We answer these questions before launch and reflect them in seller terms and support procedures.

Build trust through understandable safeguards

Trust is not a badge beside a username. We build it through clear listings, verifiable actions, predictable policies and useful support.

We distinguish identity verification from claims about quality. A seller passing identity checks does not prove that every listing is accurate. We design reporting, moderation and evidence collection accordingly.

Reviews should connect to genuine transactions, with rules for cancellations, disputes and suspected manipulation. We preserve relevant messages and fulfilment evidence under a documented retention policy, while limiting unnecessary personal-data collection.

Fraud controls work best in layers: rate limits, account security, payment-provider risk tools, transaction limits and targeted manual review. We watch for account takeover, stolen payment credentials and collusion, not only suspicious buyers.

Where we use AI to assist moderation or triage, we keep consequential decisions reviewable. We log the signals and reasoning available to human reviewers, avoid sending unnecessary sensitive information to models and provide an appeal route.

Design refunds and disputes before launch

Refunds are not simply negative purchases. We decide how partial refunds affect platform fees, seller allocations, taxes and processing costs, subject to provider behaviour and applicable rules.

We separate a customer-service refund from a card dispute. A dispute has its own deadlines, evidence requirements and financial consequences. We prevent workflows from accidentally issuing duplicate compensation while a disputed payment is being handled.

Our operations interface shows the original order, payment history, fulfilment evidence, communications and previous actions. Staff permissions are scoped, and sensitive actions require confirmation or approval according to risk.

We record who acted, what changed and why. We also design buyer and seller notifications alongside the backend workflow. When money is involved, an unexplained status change becomes a support problem even if the database is technically correct.

Keep the cloud architecture deliberately boring

Google Cloud is our preferred starting point, though we also build on AWS and Azure. On Google Cloud, a practical foundation might use Cloud Run for application services, Cloud SQL for PostgreSQL for transactional records, and Pub/Sub or Cloud Tasks for asynchronous work.

We keep ledger updates inside database transactions and use an outbox pattern when a committed change must reliably trigger downstream processing. Infrastructure does not eliminate duplicate delivery, so consumers remain idempotent.

We use Secret Manager, least-privilege service identities, encrypted connections and restricted access to production data. Hosted payment collection can reduce PCI scope, but it does not remove our security responsibilities.

Our monitoring tracks failed payment transitions, webhook processing delays, reconciliation differences and payout failures. Alerts need owners and runbooks. Backups need restore tests. A marketplace architecture is only as dependable as our ability to operate it when something breaks.

Launch narrowly and test the awkward cases

We prefer a constrained first release: a manageable geography, currency set, seller category and payout policy. Each additional dimension multiplies edge cases and support demands.

We test retries, timeouts, duplicate events, delayed confirmations, partial refunds, restricted sellers and failed payouts. Provider sandboxes are essential, but we also validate permitted live flows carefully before opening access broadly.

Our short launch checklist is:

• Map responsibilities and money movement.
• Confirm provider support and seller eligibility.
• Define order, payment and payout states.
• Verify ledger entries and reconciliation.
• Test recovery paths and staff permissions.
• Publish clear fees, timelines and policies.
• Assign support, risk and incident ownership.

Reliable marketplaces earn confidence one explainable transaction at a time. If we are the right team to help shape yours, start a project. To explore how we connect web development, product design and cloud engineering, read our related services pages.