A marketplace moving $10 million in annual GMV pushes a large share of that money through refunds, chargebacks, tax holds, seller payouts, credits, and adjustments before finance closes the year. Payment architecture governs that flow, not the checkout page alone. Checkout is one visible surface, and the architecture behind it decides who receives funds, when sellers get paid, how refunds reverse, and which records finance uses during close.
Marketplace teams often defer payment architecture because first launch rewards speed. A buyer pays, a seller receives funds, and the platform records an order. That narrow path breaks when the business adds split settlement, subscriptions, seller tiers, enterprise invoices, international tax treatment, or post-purchase entitlements, since each change adds financial states that checkout code cannot represent alone.
Rebuilding payments later is one of the highest-risk refactors in marketplace platform development. It touches buyer trust, seller cash flow, revenue recognition, compliance, support tooling, and every historical transaction record. The refactor also changes operational behavior, because support scripts, finance reports, seller statements, refund policies, and incident runbooks all depend on the same transaction model.
Payments sit inside the operating model
Payment architecture defines how the marketplace makes money, holds money, moves money, and proves what happened. It is an operating model decision expressed in code, schema, runbooks, and support workflows. Cart, orders, payments, and the always-available catalog should be treated as core services with single-source-of-truth semantics, strict audit trails, and production-grade failure handling. They sit directly on conversion and cash flow, so a delayed webhook, duplicate refund, or missing payout state becomes a customer issue within hours.
Third-party providers can process cards, manage wallets, verify sellers, calculate tax, issue invoices, and route payouts. The marketplace owns the domain model, which covers order state, seller balance, refund rules, entitlement state, settlement timing, and the financial ledger.
Click to expand A hosted checkout can cut launch effort by several weeks, and the marketplace still needs an order and payment state machine behind it. Marketplace operators must define what happens after authorization succeeds, capture fails, payout stalls, or a seller disputes a balance, none of which the conversion layer covers.
A strong payment model gives each team a common operating record. Engineering uses it to process state changes, finance uses it to close books, and support uses it to explain customer outcomes. That shared record matters during the first production incident, because without it three teams read three systems and produce three answers for one transaction.
Payment architecture also decides how quickly the company can add revenue models. A marketplace that models credits, invoices, subscriptions, and seller balances early can introduce new plans without rewriting transaction history. The reverse pattern is expensive, since a platform that treats payment success as order completion must retrofit states for authorization, capture, settlement, fulfillment, refunds, disputes, and entitlements. A marketplace processes commercial promises, not card transactions alone, and every payment event has a legal, accounting, support, and product meaning.
First-launch choices become business constraints
The first payment stack usually reflects the smallest viable transaction, where one buyer pays one seller for one item in one country with one tax treatment. That model rarely survives the next 18 months. The second year brings multi-seller carts, refunds after payout, seller plans, invoice buyers, credits, local payment methods, and tax registration questions.
Click to expand Online marketplaces already drive more than half of global e-commerce, and the top platforms alone move $3.8 trillion in GMV. At that scale, payment architecture becomes a growth control point, since every new market, seller type, and pricing model adds money movement rules. Modern flows now include wallets, account-to-account transfers, local rails, instant refunds, and agent-assisted purchases, and a checkout-only model sends the hardest work to support, finance, and incident response.
Early payment choices also shape commercial negotiation. If the system cannot represent a seller reserve, the risk team loses a control point before the first fraud review. The same choices shape product packaging, since a subscription payment that creates access directly turns enterprise contracts with purchase orders and delayed cash collection into custom exceptions. These exceptions accumulate quickly, and after six months the team often has admin overrides, spreadsheet reconciliations, manual credits, and support macros that disagree with the database.
The problem gets harder as transaction volume grows, because a manual refund review that works for 20 refunds per month fails at 400 refunds per month. Payment design needs headroom for the next business model, so the first release should carry enough structure for the next two pricing and settlement changes.
Settlement model
A basic stack collects the full payment into the platform account and pays sellers later, which raises immediate questions about money transmission, tax liability, seller cash flow, and balance reconciliation. A marketplace that plans to support multi-vendor carts needs order lines that settle independently, each with its own seller, fee, tax basis, fulfillment state, refund eligibility, and payout state. A $240 cart with three sellers, a $20 platform fee, one partial refund, and one seller-funded discount needs line-level settlement, since a single opaque charge forces finance to reconstruct the transaction after close.
The architecture must define whether the platform is merchant of record, agent, reseller, or commission-based intermediary. Under Stripe Connect that choice is explicit, where destination charges make the platform the merchant of record and other charge types shift it to the connected account. That decision also affects tax registration, invoicing, and support obligations, and it drives user communication, so the buyer receipt, seller statement, refund email, and finance export all describe the same financial event.
Settlement design should define timing too. A marketplace may capture at checkout, capture after fulfillment, or authorize first and capture after seller acceptance, and each option creates a different failure mode across expired authorizations, partial captures, unavailable inventory, and rejected seller commitments. A delayed-capture model needs rules for authorization expiry, and Visa and Mastercard authorization windows vary by transaction type, payment method, and region. A seller-acceptance model needs rules for unavailable inventory, so the platform knows whether to void authorization, capture a partial amount, or offer substitution. A services marketplace needs rules for completion, where funds move after booking confirmation, delivery acceptance, dispute expiry, or milestone approval. Settlement rules should be visible in the data model, because a provider setting buried in a dashboard cannot explain seller cash flow during a dispute.
Seller onboarding and payout controls
Seller workflows are part of the payment system. Know-your-customer checks, bank account validation, payout holds, reserves, and sanctions screening need states that product, support, finance, and risk teams can inspect. A common early error treats seller payout status as a field returned by the payment provider, which leaves the marketplace without its own seller financial state. When the provider blocks payouts, the platform cannot explain the reason, estimate release timing, or reconcile seller balances, so support teams copy provider error codes into tickets and finance loses a clear operating record.
Payment architecture should include an internal seller account model, where provider IDs are attributes of that model, not the model itself. The internal model should track verification status, payout method, reserve policy, hold reason, risk review status, tax form status, and settlement schedule, and those fields become operational controls during the first dispute cycle. Onboarding also needs a state machine that product can display, so a seller sees whether the account is awaiting identity verification, bank validation, tax form completion, risk review, or payout activation. That visibility reduces ticket volume and stops support teams from interpreting provider states without a shared source of truth.
A seller account should store verification history, showing when identity documents were requested, submitted, rejected, approved, or expired. The model should also separate seller eligibility from payout eligibility, since a seller may publish listings before a bank account is approved while payouts remain blocked. Marketplaces need controls for payout schedules, where new sellers start on a seven-day hold, high-risk categories require reserves, and trusted sellers qualify for faster settlement. Those policies belong in the internal account model, so provider payout settings reflect marketplace rules rather than replace them.
Refunds, disputes, and adjustments
Refunds are rarely symmetrical reversals. Marketplaces need to decide who funds the refund, whether the platform fee is returned, and how tax is adjusted, and they need to check whether seller payout has already occurred. The buyer entitlement may need to end, downgrade, or remain active under contract terms. Disputes add a second path, since a Visa chargeback can arrive up to 120 days after purchase, after the seller has received funds and the buyer has consumed the service. Without a ledger, teams reconstruct financial truth from provider dashboards and database records, and that process fails when volume reaches hundreds of refunds, partial credits, and chargebacks each month.
A marketplace needs immutable financial events. The minimum set includes authorization, capture, fee recognition, seller payable creation, payout, refund, dispute, reversal, credit, and manual adjustment, and each event needs a timestamp, actor, source system, provider reference, order reference, seller reference, and accounting treatment. That record gives finance and engineering the same version of financial truth. Manual adjustments need the same discipline, so a $50 goodwill credit, a seller clawback, or a tax correction never lives only in an admin note. Every adjustment should carry an approval record and a reason code, and finance should trace it during close without asking engineering to query production data.
Refund policy should also account for fulfillment state, because a refund before fulfillment has different accounting treatment from a refund after delivery. A marketplace that sells services needs additional states, where a cancellation 12 hours before a booking produces a partial refund, a seller fee, and retained platform revenue. Dispute records should store evidence deadlines, since chargeback responses often require order details, delivery proof, communications, refund history, and seller policies. The system should also track dispute liability, because one marketplace absorbs chargebacks while another makes sellers carry liability after payout. Adjustment discipline becomes essential during tax corrections, where a sales tax reversal needs a link to the original jurisdiction, taxable basis, invoice, and refund event.
Entitlements and pricing promises
Payment systems also enforce product promises. A seller subscription tier, promoted listing package, buyer membership, service deposit, or usage-based plan must map to application entitlements. An entitlement should answer a direct question, such as whether this seller can post 50 listings, receive premium placement, accept bookings, issue credits, or access analytics. A pricing partner should be judged on three concrete abilities, which are mapping pricing promises to enforceable entitlements, setting up safe migrations and billing hooks, and measuring experiment results through instrumentation. Without those abilities, pricing work becomes presentation-layer work, where the team changes screens and rates while the platform lacks durable rules for access and billing.
This matters when a marketplace moves from transaction fees to subscriptions, bundles, credits, or enterprise contracts. Billing systems such as Stripe Billing, Chargebee, Recurly, and custom ledger services each impose a model, so the marketplace should decide the model before the provider becomes the architecture. That decision belongs in schema, events, APIs, and customer contracts. Pricing promises also create historical obligations, since a seller grandfathered into a 12% commission plan needs a rule that survives provider changes and billing migrations. The same applies to credits and minimum commitments, where a buyer with 1,000 prepaid usage credits keeps that balance across refunds, disputes, and contract renewals.
Entitlement records need their own lifecycle, where access can start, pause, expire, renew, downgrade, or terminate for reasons separate from payment status. A failed card payment should not automatically terminate every entitlement, because grace periods, contract terms, invoice disputes, and manual grants all change access rules. The model should also support backdated changes, since enterprise contracts often start on the first day of a month while signature and invoicing happen later.
Provider selection is one layer
Build-versus-buy discussions often focus on whether the team should create payment rails or use a provider, and that frame is too narrow for most marketplace teams. A marketplace should buy regulated payment processing in most cases and build the domain layer that controls order state, financial events, entitlements, seller balances, and reconciliation. Providers supply rails, regulated services, risk tools, token storage, settlement files, and payout infrastructure, while the marketplace supplies product-specific financial truth. Founders should apply the same build-versus-buy lens to the application layer, not only to the rails.
Payment orchestration has a place when the platform needs multiple processors, regional routing, payment method fallback, or authorization rate management. For most early marketplaces, orchestration belongs after the primary financial domain model, since the first release needs clean ownership for orders, payments, payouts, webhooks, and ledger events. The first production version should isolate provider calls behind adapters, so checkout, refunds, payouts, webhooks, and disputes call internal services and those services call Stripe, Adyen, PayPal, Braintree, or Mangopay. That separation reduces migration cost later and gives the team a place to handle idempotency, retries, event ordering, and provider-specific edge cases.
Provider selection should start with the merchant model. A team should know whether it needs separate seller accounts, platform-controlled charges, direct charges, destination charges, escrow-like flows, or invoice collection, then test the shortlist against specific flows. The test set should include partial refunds, failed payouts, seller verification failure, chargeback after payout, delayed capture, and multi-seller settlement. Vendor evaluation should include data access, so the team gets settlement files, balance transactions, dispute evidence, payout references, fee records, and webhook payloads. It should also include operational support, because a marketplace with daily payout volume needs clear escalation paths for frozen accounts, blocked payouts, and settlement file delays.
Commercial terms matter after the model is clear, where basis points, fixed fees, cross-border charges, dispute fees, and payout fees affect margin by category. A 40-basis-point difference on $50 million in GMV equals $200,000 per year, and that number matters, yet it should follow the architecture decision.
The decision matrix
The following matrix is the minimum artifact a technical founder should complete before selecting a payment provider or commissioning marketplace platform development. Engineering, finance, support, legal, and product should review it together.
| Decision area | Early launch shortcut | Later constraint | Required architectural decision |
|---|---|---|---|
| Merchant model | Platform collects all funds | Tax, liability, and money movement exposure | Define merchant of record, agent, reseller, or commission model |
| Order model | One charge per checkout | Multi-seller carts and partial refunds fail | Model order, order line, payment intent, and settlement unit separately |
| Seller account | Store provider account ID only | Limited control over payout state and risk status | Create internal seller financial account with provider mappings |
| Ledger | Use provider dashboard as source of truth | Reconciliation depends on manual review | Store immutable financial events and derived balances |
| Refunds | Reverse payment when requested | Fee, tax, entitlement, and seller payout conflicts | Define refund policy by order state, payout state, and entitlement state |
| Pricing | Hard-code commission rate | Subscriptions, bundles, and enterprise billing need rewrites | Separate pricing rules, billing events, and entitlement checks |
| Tax | Add tax calculation at checkout | International expansion forces order model changes | Store tax jurisdiction, tax basis, exemptions, and invoice records |
| Risk | Rely on provider defaults | Fraud, seller abuse, and chargebacks lack workflow | Define risk states, holds, reserves, and manual review queues |
| Reconciliation | Export CSVs monthly | Finance close slows as volume grows | Build daily settlement matching and exception queues |
| Provider abstraction | Call one provider API throughout codebase | Migration touches checkout, orders, refunds, and payouts | Isolate provider calls behind payment, payout, and webhook adapters |
Click to expand This matrix should be completed before the first production payment, since changing one row later can require data migration, contract changes, support retraining, and finance process redesign. The artifact should produce concrete engineering tasks, where each required decision maps to tables, events, APIs, tests, runbooks, and monitoring. A matrix that never reaches implementation has limited value, so the test is whether a new engineer can read the records and explain how money moves from authorization to payout.
The matrix should also identify ownership, giving each row one accountable executive, one engineering owner, and one operational owner. That structure keeps payment architecture from becoming an engineering-only concern, because legal owns merchant model risk, finance owns close, and support owns customer communication. It should include acceptance criteria, so a partial refund shows the affected order line, tax reversal, seller receivable, platform fee treatment, and entitlement change. It should include data retention decisions as well, since payment records, tax records, dispute evidence, and customer communications often carry different retention requirements. Each decision should produce a test case that runs in staging before the first live payment and again before every provider migration.
A concrete failure pattern
A services marketplace launched with direct card charges into the platform account and monthly manual payouts, and the first version supported one buyer, one seller, one service, and a 15% platform commission. Eighteen months later, the marketplace reached about $2.4 million in annualized GMV across 900 sellers, and enterprise buyers asked for invoice billing, sellers requested weekly payouts, and the product team introduced subscriptions for premium seller placement. The payment model could not support those changes cleanly, because orders had no line-level settlement state, refunds were stored as negative order totals, and seller balances were calculated from live queries instead of a ledger.
The rebuild took five months, during which the team froze billing changes, migrated historical orders, reconciled payout balances manually, and wrote support scripts for disputed legacy transactions. A better first version would have taken three to five additional weeks and created an order state machine, internal ledger, seller account model, webhook processing, and provider adapter. This is the false economy of the quick MVP in a payment stack, where the later refactor consumed a full quarter of senior engineering capacity and delayed revenue work during migration, since the same engineers owned enterprise billing and subscription infrastructure. The cost showed up in operations too, as finance needed two analysts to reconcile legacy transactions for close and support needed a separate escalation path for old refunds.
That pattern repeats across marketplace builds. The initial shortcut creates speed for one launch milestone, then creates drag across engineering, finance, risk, and support. The technical debt becomes commercial debt, since sales teams hesitate to offer enterprise terms when engineering cannot confirm invoice timing, access state, and settlement treatment. Investors notice the same issue during diligence, where a marketplace with unclear payment records faces harder questions about revenue quality, seller liabilities, and refund exposure.
The deeper cost sits in decision speed. Product leaders stop proposing pricing changes because each change requires payment investigation, and engineering teams build around constraints by adding exception tables, admin tools, and manual exports instead of a coherent transaction model. Finance teams absorb the ambiguity as month-end close grows from two days to six, because analysts must reconcile provider exports against application records. Support teams carry the same burden, since a buyer refund question requires payment dashboard access, order database review, and seller payout lookup. Those costs rarely appear in the first-launch budget, and they surface later as delayed releases, longer close cycles, lower support quality, and weaker diligence materials.
The services a marketplace should own
Marketplaces should own the systems that define financial truth. Providers can process transactions, while the platform keeps durable records that stay valid if the provider changes. These services do not require separate deployments on day one, and in a smaller product they start as modules inside one application with clear interfaces and separate data ownership. The service boundary matters as much as the deployment model, so each service needs a clear owner, clear events, and clear rules for state transitions. A modular monolith can work well for the first release, where the important boundary is data authority, not the number of repositories or containers. The team should define which module owns each record, so orders do not write ledger balances directly and payments do not grant product access directly. Events provide the contract between modules, and order captured, refund approved, seller payable created, payout initiated, and entitlement revoked are examples of durable domain events.
Click to expand Order service
The order service owns buyer intent, seller commitments, item or service details, delivery state, cancellation state, and the link to payments, and it should distinguish checkout creation, authorization, capture, fulfillment, completion, cancellation, and refund eligibility. A single status field named paid or complete is insufficient for a marketplace, so a production-ready model uses explicit states and records every transition with actor, timestamp, reason, and source system. The service should support line-level state, where one item ships, one seller cancels, and one service stays pending. That model protects the customer experience, since buyers see accurate status, sellers see accurate obligations, and support can explain what happened without reading raw payment records.
The order service should also record commercial terms, which include commission rate, seller discount, buyer promotion, tax basis, cancellation rules, and fulfillment deadline. Those terms should be stored at order creation, so if the marketplace changes pricing next month, last month’s order still keeps its original commercial record. The model should also store promise dates, since delivery windows, cancellation deadlines, service start dates, and acceptance periods affect refunds and settlement. A physical goods marketplace needs shipping and return states, and a services marketplace needs booking, attendance, delivery, acceptance, and dispute windows. The service should expose read models for support, so support sees customer-facing status and operational status without querying payment provider records.
Payment service
The payment service owns payment intents, captures, refunds, disputes, provider webhooks, idempotency keys, and payment method references, and it should receive provider events through a durable queue such as SQS, Pub/Sub, Kafka, or RabbitMQ. Webhook processing must be idempotent, because providers retry events, events arrive out of order, and operations teams replay messages during incident response. Payment code that assumes one event, in order, one time will fail under normal production conditions, and duplicate refunds, missed captures, and incorrect dispute states are predictable outcomes. The service should store provider event payloads in raw form and normalized internal events that the rest of the platform can consume, which supports audit work and provider changes, so engineers can inspect the original provider message while the domain model stays stable.
Payment APIs should use explicit idempotency keys, so refund creation, capture, and payout initiation tolerate client retries and worker restarts. A production payment service treats external provider status as input, and the internal state machine decides which domain event follows from that input. The service should track every external call, recording request ID, provider ID, idempotency key, response code, latency, and retry count, and it should protect against double execution so a refund button clicked twice creates one refund intent and one provider request. Dispute workflows need the same rigor, where evidence submitted to a provider links to the order, seller, buyer, communications, delivery proof, and policy version.
Ledger service
The ledger records financial events and produces balances, separating buyer receivables, seller payables, platform revenue, tax liabilities, processor fees, refunds, chargebacks, and reserves. A first ledger does not need to match a banking core in breadth, yet it does need immutable entries, clear account types, structured event accounting, and reconciliation against provider settlement files. The ledger should derive balances from events and avoid balance fields that teams update directly from multiple workflows, since direct balance updates create silent errors where a manual credit, provider fee correction, or chargeback reversal overwrites state without a trace. A strong first ledger can be small, starting with account types, event types, journal entries, references, and daily reconciliation reports. Ledger entries should carry source references, so an entry tied to order_line_id, seller_account_id, payment_intent_id, and provider_settlement_line_id can be traced quickly.
The ledger should distinguish operational balance from accounting treatment, since a seller payable and platform revenue recognition may occur at different points in the order lifecycle. The first version can use double-entry accounting patterns without building a general ledger product, where each business event creates balanced entries with explicit accounts. For example, capture increases cash receivable and creates platform fee revenue, tax liability, and seller payable entries, while refund reverses some entries and creates a receivable from the seller. Ledger records should be append-only, so corrections create new entries that reference the original event. This discipline protects auditability and prevents engineers from changing historical balances during incident response.
Entitlement service
The entitlement service owns access granted by payment or contract, so a buyer membership, seller subscription, promoted listing, usage credit, or digital purchase is checked through entitlements. Payment records should remain payment records, and product access rules should live in entitlement records that change without rewriting financial history. This separation keeps payment history stable while product rules evolve, and it supports enterprise billing where access begins before cash collection. A B2B buyer may sign a $60,000 annual contract with net-30 payment terms, so the platform grants access at contract start, invoices later, and tracks cash collection separately. That scenario fails when access is inferred from card payment success, because contract state, invoice state, cash collection state, and entitlement state need distinct records.
Entitlements should have start dates, end dates, source events, grant reasons, and revocation rules, so support can tell why access exists and when it ends. Usage-based entitlements need counters and audit records, where a buyer using 300 of 1,000 prepaid credits needs traceable consumption tied to orders, services, or API calls. Entitlement checks should be centralized, so product teams do not copy subscription logic into listing creation, analytics access, messaging, and promotion placement. A central entitlement service also improves migration safety, since a billing provider change should not require product engineers to rewrite access checks across the application. Manual grants need approval controls, where a support manager extends access for seven days and a revenue leader approves a three-month enterprise concession.
Risk controls belong in the first architecture
Fraud and abuse controls are often added after the first chargeback cycle, and that sequence creates avoidable exposure. Marketplace risk has four domains, which are buyer fraud, seller fraud, payment fraud, and operational abuse, and each domain needs states, thresholds, and review workflows. A practical first version should include payout holds for new sellers, velocity limits on high-risk purchases, manual review for abnormal refund rates, and reserve rules for categories with delayed fulfillment. These controls can be simple at launch, yet they need a place in the model, because a hold reason stored only in a support note will not control payout logic. New sellers can receive a seven-day payout hold until identity checks clear and the first order is fulfilled, high-value orders can require review when the buyer account is under 24 hours old, refund rules can flag sellers above category norms, and reserve rules can hold 10% to 20% of payouts for services delivered over multiple weeks.
Banks and payment providers are redesigning their own architectures for similar reasons, since payment systems now need faster decisioning, clearer visibility, and stronger controls across fragmented channels. Marketplaces face the same pressure with smaller teams and tighter timelines, which makes the early domain model more important, because the platform needs specific places to store risk state, review decisions, payout holds, and dispute outcomes. Risk states should feed payout logic directly, so a seller marked for review does not receive automated settlement until the review decision closes. The same principle applies to buyer risk, where a high-risk buyer moves through payment review before the platform confirms fulfillment or releases seller inventory.
Risk controls should also record who made each decision, so a manual approval carries reviewer, reason, timestamp, evidence, and next review date. The first risk queue can be simple, needing case ID, account ID, transaction ID, category, status, owner, due date, and decision outcome. Thresholds should be configurable, so engineering does not deploy code each time risk changes a reserve percentage or refund review threshold. Risk events should also feed reporting, so fraud loss, dispute rate, seller reserve balance, and payout hold volume stay visible weekly.
Tax and invoicing need early data discipline
Tax is often treated as a checkout calculation, which leaves the marketplace without the records needed for refunds, exemptions, audits, and international expansion. A tax calculation should produce durable data, so the order stores jurisdiction, tax basis, tax rate, exemption status, tax provider reference, and invoice reference. International expansion raises the cost of weak tax records, since VAT, GST, marketplace facilitator rules, and seller location all affect liability. The payment model should know who is responsible for tax collection, because merchant of record, agent, reseller, and marketplace facilitator models create different obligations. Tax refunds need original calculation references, so a partial refund on one order line reverses the correct tax amount for the correct jurisdiction.
Enterprise invoicing adds another layer, where purchase orders, invoice approvals, billing contacts, tax exemptions, and net terms need explicit records. A card-first payment model usually lacks these states, so the enterprise path becomes a set of manual invoices and support exceptions. Invoice records should link to orders, entitlements, contracts, payments, credits, and ledger entries, so finance traces cash collection without asking engineering for custom exports. Tax and invoice decisions also affect customer communication, so the buyer receipt, seller statement, invoice, credit memo, and refund email agree on amounts and timing.
Reconciliation should run daily
Monthly CSV exports do not scale for marketplaces with active refunds, payouts, fees, disputes, and tax obligations, so finance needs a daily process that compares internal events against provider settlement files. Daily reconciliation should match captures, refunds, fees, payouts, chargebacks, reserves, and adjustments, and each exception should enter a queue with an owner, status, and resolution note. A $19.40 processor fee mismatch can wait, while a missing $4,800 seller payout needs same-day review. The process should produce three outputs, since finance needs settlement reports, engineering needs exception data, and support needs customer-facing status. The architecture should store provider settlement file IDs and line references, which make the difference between a two-minute investigation and a three-hour Slack thread.
Reconciliation also protects migrations, because when a marketplace changes providers it needs confidence that old events, new events, and balances all tie to external records. Exception categories should be explicit, including missing provider event, missing internal event, amount mismatch, currency mismatch, duplicate settlement line, and unexpected fee, and each category should have a resolution path where engineering fixes system errors, finance approves accounting adjustments, and operations handles provider tickets. A daily process also improves month-end close, so finance enters close with a known exception list instead of discovering mismatches during reporting week.
Daily reconciliation does not require a large team, since a marketplace can start with scheduled settlement imports, deterministic matching rules, and an exception table. The process should run even when volume is low, because early execution finds schema gaps before the first high-volume month. Reconciliation should also track aging, so an exception open for one day carries different urgency from one open for 14 days. The system should produce a clear balance bridge, so finance sees beginning balance, captures, fees, refunds, disputes, payouts, reserves, adjustments, and ending balance.
Observability is part of payment design
Payment systems need operational visibility from the first production transaction, and standard application logging is insufficient for money movement. The team should track authorization rate, capture failure rate, refund success rate, webhook delay, duplicate event count, payout failure rate, dispute rate, and reconciliation exceptions, and each metric needs an owner and alert threshold. A 15-minute webhook delay can block fulfillment, and a failed payout batch can create hundreds of seller tickets before engineering sees an error. Logs should include internal IDs and provider IDs, so support searches by order ID, payment intent ID, seller ID, payout ID, and dispute ID. Runbooks should cover duplicate webhooks, late provider events, failed captures, refund failures, payout reversals, and chargeback notifications, since these incidents occur in normal operations, not only during outages.
Observability also improves product decisions, so when a new wallet raises authorization rates in one region, the team needs data tied to payment method, issuer, country, seller category, and order value. Dashboards should separate customer impact from provider status, because a provider outage matters differently when it affects 2% of transactions versus all payouts in one region. Alerts should route to the team that can act, where a reconciliation exception belongs with finance and engineering and a seller payout failure also belongs with support operations. The payment system should support incident review, so each incident leaves behind event timelines, failed state transitions, and customer impact counts.
A useful payment dashboard separates leading indicators from lagging indicators, where webhook delay and capture failure rate lead and dispute rate and reconciliation backlog arrive later. The dashboard should also show money at risk, so a queue with 12 failed payouts means more when those payouts total $180,000. Traceability should cover customer-facing timelines, so support sees when payment was authorized, captured, refunded, disputed, paid out, or reversed. Incident reviews should produce model changes when needed, so if a duplicate webhook creates a duplicate credit, the corrective action belongs in idempotency design.
The 10-question payment architecture review
Before choosing Stripe Connect, Adyen for Platforms, Braintree, PayPal Commerce Platform, Mangopay, or a custom payment layer, marketplace leaders should answer these questions in writing.
- Who is merchant of record for each transaction type?
- Can one checkout contain items from multiple sellers?
- Can one order line be refunded without changing the rest of the order?
- Who funds refunds after seller payout?
- What event creates platform revenue for accounting purposes?
- How are seller balances calculated and audited?
- What states exist between seller signup and first payout?
- Which entitlements are created by payment, subscription, contract, or manual grant?
- What happens when a provider webhook arrives twice or arrives late?
- How would the platform migrate from one provider to another in 12 months?
These answers should appear in architecture decision records before implementation starts, and they should be reflected in database schema, API contracts, runbooks, and test cases. A senior software development team asks these questions before writing checkout code, while a team focused only on first-launch screens defers them until the product has live money movement, active sellers, and customers who expect continuity. The review should include finance, support, product, legal, risk, and engineering, since finance owns close, support owns customer explanations, and product owns the commercial promises that payments must enforce.
A two-hour review can prevent months of remediation, and the output should be a written decision record, not meeting notes. The review should end with testable statements, for example that a seller-funded refund after payout creates a seller receivable and sends the balance negative until the next payout cycle. Statements at that level give engineers and finance a shared design target and expose gaps before provider integration begins. The review should also define non-negotiable failure behavior, so the team knows what happens when capture fails, payout fails, tax calculation fails, or a provider webhook arrives late. Every answer should tie to an owner, where a merchant model answer belongs with legal and finance and idempotency belongs with engineering. The same review should happen before major pricing changes, because subscriptions, credits, bundles, enterprise invoices, and reserves all change payment architecture.
Implementation sequence for the first release
A marketplace can build the right payment foundation without slowing launch for a full quarter, and the sequence matters. Start with the money movement model, documenting each transaction type, each actor, each account, and each state from authorization to payout. Then define the order model, separating order, order line, payment intent, settlement unit, fulfillment state, and refund eligibility. Next define seller financial accounts, storing provider mappings, verification state, payout method, hold reason, reserve policy, tax form status, and payout schedule. After that, define financial events and ledger entries, so capture, fee, payable, payout, refund, dispute, reserve, credit, and adjustment events have stable schemas.
Then integrate the provider through adapters, so checkout, refunds, webhooks, disputes, and payouts call internal services first. Build reconciliation before launch, since a daily settlement import and exception queue catch early gaps while transaction volume is still manageable, and add observability at the same time so payment metrics, logs, traces, and runbooks exist before the first marketing campaign drives traffic. This sequence creates a practical first release where the team can still use hosted checkout, provider onboarding, and provider risk tools. The difference is control, since the marketplace keeps its own financial truth while outsourcing regulated processing to a specialist.
Design the stack for the next business model
Payment architecture should be sized for the next two business models, since the first transaction is too narrow a design target. If the marketplace expects international sellers, design for tax jurisdiction and payout method diversity, and if subscriptions are likely, define entitlement events early. If enterprise customers are in the plan, separate invoicing, access, and cash collection from day one, because a card-first model cannot carry contract start dates, purchase orders, usage minimums, invoice approvals, and net-30 collection without additional state.
The practical path is direct. Write the money movement model, define the order and ledger state machines, and select a provider that fits the merchant model. Build provider adapters instead of scattering provider calls through application code, and test refunds, disputes, payout failures, duplicate webhooks, partial captures, and late settlement files before launch. Do this before commissioning marketplace platform development or signing a payment provider contract, because the payment architecture will support the business model or constrain it. Treat it as a board-level product decision, then build checkout on top of it.
Algorithmic runs backend and payment infrastructure builds that put the order state machine, ledger, and provider adapters in place before the first live payment. Start a conversation if you are commissioning a marketplace or reworking a payment model that first launch has outgrown.
