What API and data model would support a new Terminal workflow for marketplaces

Problem Statement Description

Product context: Stripe is financial infrastructure for internet businesses; its products include payments, Checkout, Billing, Connect, Radar, Issuing, Terminal, and tax tools.

Stripe Terminal enables businesses to accept in-person payments, while marketplaces often need to support many connected sellers, physical locations, readers, staff members, orders, payouts, refunds, and compliance obligations under one platform experience. In this interview, you are asked to define the API and data model needed to support a new Terminal workflow for marketplaces.

Focus on the platform operator, connected merchants, in-store staff, and developers integrating the workflow. The core challenge is that a marketplace must orchestrate in-person payments across multiple sellers while preserving accurate ownership of funds, devices, customer interactions, reporting, permissions, and operational state.

Your response should describe the technical product shape: the key entities, relationships, API operations, lifecycle states, permissions, and integration considerations. You should also address how the design supports developer experience, reliability, security, compliance, and future extensibility without prescribing UI screens or writing implementation code.

The experience should consider:

- How marketplace platforms create, manage, and act on behalf of connected sellers using Terminal.

- How readers, locations, staff, orders, and payment attempts are represented and associated with the right merchant context.

- What API actions are needed for setup, payment collection, cancellation, refunding, reconciliation, and status tracking.

- How the model handles money movement, fees, settlement, reporting, disputes, and auditability.

- Required authentication, authorization, permission boundaries, and data isolation between platform and sellers.

- Reliability concerns such as idempotency, offline/failed reader states, retries, webhooks, and observability.

- Privacy, fraud, PCI/compliance, and global regulatory considerations for in-person marketplace payments.

- Rollout and migration considerations for existing Terminal or marketplace integrations.

The goal is to evaluate your ability to translate a marketplace Terminal workflow into a coherent API and data model that is developer-friendly, operationally safe, financially accurate, and scalable across many merchants, locations, and payment scenarios.