Stripe Connect Architecture for a UK Marketplace

The payout feature that could not be tested where it mattered

On an Appycodes engagement for a UK wholesale marketplace, the delivery record shows a vendor bulk-payout update blocked because the relevant feature was not available in staging. The next work separated write-offs from the vendor payout source, and a later record marked that payout work complete. Months afterwards, a multi-country Stripe-account change and a new PaymentIntent checkout reached implementation while full integration testing was temporarily blocked by other backend testing; the team then moved into webhook and order-level data testing.

The hard lesson was not “Stripe is difficult”. It was that money-moving behaviour cannot be accepted from a local happy path. A payout source, a write-off, the buyer charge and the seller statement are different accounting facts. If staging cannot exercise the same route, account ownership and webhook scope as production, “payment succeeded” proves too little.

Our public UK wholesale marketplace case study explains the wider, long-running ecommerce and reconciliation context. The practical conclusion for a new UK marketplace is simple: make the production money topology reproducible in test before the first seller is owed funds.

Choose the charge type from the transaction shape

Stripe documents three Connect charge types. The choice determines where the charge appears, how funds move, which statement details are used and which Stripe balance is debited for refunds and chargebacks. Stripe: how Connect charges work

Stripe says separate charges and transfers add complexity and are intended for cases such as multiple recipients, a recipient chosen after payment or transfer timing independent of the charge. It also warns that refunding the platform charge does not automatically reverse associated transfers; the platform must reconcile or reverse them. Stripe: separate charges and transfers

The on_behalf_of parameter is a settlement decision, not decorative metadata. Stripe says it changes the business-of-record treatment within Stripe, the connected account country and fee structure, statement descriptor and payout timing. That setting must agree with the seller contract, checkout copy, invoice, support process and tax position. It does not replace a qualified legal conclusion about who is merchant of record. Stripe: indirect charges and on_behalf_of

The Appycodes Marketplace Charge Route Gate

Before implementation, score five gates from 0 to 3: 0 undecided, 1 assumed, 2 documented but untested, 3 documented and tested with retained evidence. The maximum is 15. Contract and Liability are hard gates: either at zero means the team should not ship a live money route, whatever the total.

This is an architecture-readiness model, not legal or financial advice and not a statistical risk score. Its value is forcing five decisions that a checkout mock-up hides. Apply it per transaction family: a marketplace can legitimately use direct charges for seller-owned stores and separate charges for a platform-curated multi-seller basket, provided each route remains explicit and reconcilable.

Your order database needs a money ledger

Do not make the order row carry every financial state. An order describes the commercial purchase; the money ledger describes movements and obligations. Keep amounts as integers in the currency's minor unit and retain the route version used when the buyer paid.

This ledger also supports a UK requirement that payment code often discovers too late. HMRC's current platform-operator guidance requires reportable seller data that can include quarterly amounts paid after deductions, fees or commissions withheld, transaction counts and available payout-account details. Stripe reports can help, but the marketplace must preserve the seller-level meaning of each deduction. HMRC: collect and verify digital-platform seller information

A destination-charge implementation with explicit boundaries

The example below is appropriate only for a one-seller, platform-led order whose Charge Route Gate has passed. It creates the provider object and immediately persists the internal attempt. It intentionally omits on_behalf_of; adding that field would change settlement semantics and should be a reviewed route version, not an incidental refactor.

// A platform-led, one-seller order. Use only after the commercial
// model confirms that the platform owns the customer-facing charge.
const intent = await stripe.paymentIntents.create(
  {
    amount: order.totalMinor,
    currency: "gbp",
    automatic_payment_methods: { enabled: true },
    application_fee_amount: order.platformFeeMinor,
    transfer_data: { destination: seller.stripeAccountId },
    metadata: {
      order_id: order.id,
      seller_id: seller.id,
      charge_route: "destination_v1",
      allocation_version: order.allocationVersion,
    },
  },
  { idempotencyKey: `checkout:${order.id}:${order.paymentAttempt}` },
);

await db.paymentAttempt.upsert({
  where: { providerIntentId: intent.id },
  create: {
    orderId: order.id,
    providerIntentId: intent.id,
    route: "destination",
    grossMinor: order.totalMinor,
    feeMinor: order.platformFeeMinor,
    sellerMinor: order.totalMinor - order.platformFeeMinor,
    currency: "GBP",
    status: intent.status,
  },
  update: { status: intent.status },
});

The idempotency key prevents a network retry from creating a second PaymentIntent for the same attempt. Metadata is useful for support, but it is not the ledger: it has limits, can be edited and does not model later allocations or reversals. Persist the provider ID before returning the client secret, and require the authenticated order owner to retrieve it.

Do not mark the order fulfilled from the browser success page. Stripe recommends verifying webhook signatures from the raw request body, returning a successful response quickly and processing asynchronous work separately. Connect integrations may need both platform-scope events for destination or separate charges and connected-account events for direct charges, onboarding and payout failures. Stripe: webhook endpoint guidance · Stripe: Connect webhooks

1. Verify and record. Store the event ID and account context under a unique constraint before queueing work.
2. Fetch and reduce. Retrieve the current provider object when needed, then apply an allowed state transition to the payment attempt.
3. Post ledger movements. Create immutable allocation, transfer, fee, refund or dispute entries; do not rewrite history.
4. Reconcile. A scheduled job compares internal open items with Stripe balance transactions and raises owned exceptions.

For a destination-charge refund, decide whether seller funds and the platform fee should also be reversed. Make those two decisions explicit in the case record:

await stripe.refunds.create(
  {
    payment_intent: payment.providerIntentId,
    amount: refund.amountMinor,
    reverse_transfer: true,
    refund_application_fee: refund.refundPlatformFee,
    metadata: { refund_id: refund.id, order_id: payment.orderId },
  },
  { idempotencyKey: `refund:${refund.id}:${refund.attempt}` },
);

A partial refund needs a deterministic allocation rule—per line, pro rata or operator-selected—and should never reverse more seller funds than the refunded lines justify. If a connected balance cannot cover a reversal, keep the buyer refund and seller recovery as separate statuses so customer service can see what happened.

UK checks that sit outside the PaymentIntent

Payments regulation

The FCA says that providing payment services as a regular business activity generally requires authorisation or registration unless an exclusion or exemption applies. Its commercial-agent guidance warns that acting for both payer and payee is likely to require authorisation, and that control of funds before the payee receives them is a relevant indicator. Use a regulated provider such as Stripe Connect as designed, but have a UK payments specialist review the contractual and operational flow—especially if the platform delays, pools, redirects or manually releases money. FCA: commercial agent exclusion and payment-services perimeter

Seller onboarding and reporting

Stripe-hosted or embedded onboarding is preferable to collecting sensitive verification material yourself because Stripe can collect connected-account requirements and update the flow as requirements change. Stripe: embedded onboarding But UK platform reporting is a separate data product. HMRC requires reporting platform operators in scope to collect and verify specified seller details, retain reportable transaction information and submit seller reports. Build an explicit seller-reporting profile with provenance and refresh rules rather than copying whatever fields happen to be visible from Connect.

Tax, invoices and customer promises

Decide who supplies the goods or service, who issues the VAT invoice, who sets refund terms and who handles chargebacks before release. Stripe's route can support that model; it cannot invent it. Keep tax calculations, invoice records and Connect transfers joined by your order and allocation IDs, not by customer email or statement text. This guide is technical and operational guidance, not legal, tax, financial or regulatory advice.

Six failure modes to test before live payouts

1. Seller onboarding is “complete” but a capability is inactive

Persist capability and requirement states separately from your own seller status. Block the specific action that needs the capability, explain the next step and refresh from account events. Do not reduce onboarding to one boolean.

2. Staging uses a different money topology

A test platform with no representative connected accounts, webhook scopes or payout path cannot prove the production design. Maintain test sellers for every account configuration, seed the same fee rules, and rehearse onboarding expiry, disabled payouts, refunds and disputes. This is the exact class of gap exposed in the Appycodes marketplace record.

3. The checkout succeeds but the webhook is delayed

The browser should show a processing state and poll your order endpoint. A reconciliation worker can retrieve the PaymentIntent and safely close a missing event path. Never fulfil because a query string says success=true.

4. A refund leaves the seller transfer untouched

Destination and separate-charge routes debit the platform for refunds. Decide whether to reverse seller funds, absorb the cost or recover it from future earnings. Record the buyer refund and seller recovery independently.

5. A multi-seller basket is forced through one destination

One destination charge has one connected-account destination. If the basket has several sellers, split the commercial orders before payment or use separate charges and transfers with explicit allocations. Do not hide a second seller's entitlement in an offline spreadsheet.

6. The team reconciles orders, not balances

An order total can be correct while fees, disputes, reversals or payouts are wrong. Reconcile from balance transactions to ledger movements and from ledger movements to orders. Alert on orphan provider objects, duplicate allocations, negative seller balances and transfers with no accepted fulfilment state.

Recommendations by UK marketplace type

After real marketplace work, Appycodes recommends one executable money-flow specification before payment UI begins: named contracting parties, charge route, fee formula, settlement setting, transfer timing, refund allocation, dispute owner, payout controls and ledger postings. Then test that specification with representative connected accounts and failure fixtures. Our B2B marketplace development service covers the product, payment, seller-operations and reconciliation layers together.

Primary sources

• Stripe: Connect charge types, balance liability and chargebacks
• Stripe: separate charges, transfers, refunds and reversals
• Stripe: webhook signatures, asynchronous handling and testing
• Stripe: embedded connected-account onboarding
• FCA: payment services and the commercial agent exclusion
• HMRC: collect, verify and report digital-platform seller information

Technical and operational guidance, not legal, regulatory, tax, accounting or financial advice. Have qualified UK advisers confirm your contracts, payment-services perimeter, VAT treatment and seller-reporting obligations.