Marketplace Transaction Architecture Playbook

Design marketplace transactions around explicit authority, atomic reservations, protected payment operations, and accountable reconciliation and recovery.

trigger="A marketplace is adding a transaction flow or needs to correct inconsistent inventory, payment, fulfillment, or settlement state." owner="The transaction service owner, accountable for the business operation across system boundaries." participants={["Product owner", "Inventory owner", "Payments engineer", "Finance and operations owners", "Security reviewer", "Legal or compliance adviser where applicable"]} prerequisites={[ "A participant and authority map, agreed commercial terms, and a defined transaction success state.", "Payment-provider contracts and capabilities for the selected accounts, regions, and payment methods.", "An inventory authority, versioned state model, and approved handling for uncertain or disputed outcomes." ]} outputs={[ "A transaction state and authority model with invariants, owned transitions, and audit evidence.", "A durable command and integration design with duplicate, timeout, and recovery behavior.", "A reconciled pilot, fault-test record, operator runbook, and release decision." ]} doneWhen={[ "Concurrent attempts cannot violate the tested inventory and transaction invariants.", "Payment, refund, transfer, and fulfillment outcomes are recorded separately and reconciled.", "Duplicate and delayed events cannot bypass authorization or repeat a protected effect.", "An operator can resolve a discrepancy through an authorized, auditable action without guessing." ]} />

Design the transaction before the marketplace surface

Search, listings, and checkout screens help participants transact. They are not the authority for whether inventory is available, payment succeeded, or a seller should receive funds.

This playbook addresses one end-to-end transaction, including failure and recovery. It complements multi-tenant SaaS architecture, which covers broader tenant boundaries, and event-driven systems, which covers reliable asynchronous implementation.

Start with one bounded flow and its participant responsibilities. A B2B equipment marketplace might involve a buyer organization, seller organization, approver, payment provider, delivery partner, and platform support team. Their authority differs. Do not reduce that model to a single user role.

1. Agree commercial and operational authority

The product owner identifies who can list an item, reserve it, accept terms, authorize payment, cancel, confirm fulfillment, approve a refund, and resolve a dispute. Record whether the action belongs to a person, organization, service, or external provider.

The finance and legal owners determine the commercial and regulatory arrangement before engineers choose the money flow. Merchant or seller roles, funds handling, tax, identity checks, consumer rights, and settlement obligations depend on the actual model and jurisdictions. A payment API integration does not itself establish that the platform may hold funds or offer escrow.

| Fact | Authoritative owner | Derived views | | --- | --- | --- | | Listing details | Catalog owner or contracted seller feed | Search and recommendation indexes | | Available quantity or appointment | Inventory or scheduling authority | Availability cache | | Accepted terms and price | Transaction service under approved policy | Buyer and seller dashboards | | Provider payment state | Payment provider, observed by payments integration | Local payment projection | | Fulfillment state | Agreed fulfillment authority | Tracking and notifications | | Amounts owed and settled | Finance-owned records with provider reconciliation | Seller statements and reporting |

A provider is authoritative for its own payment records, not for every commercial decision in the marketplace. An order can require manual review even after payment succeeds.

Gate: every important fact has an owner and a conflict rule. If two integrations can independently overwrite the same business fact, resolve that authority before building retries.

2. Define states and invariants separately

Model business state, payment state, fulfillment state, and integration-processing state separately. One generic status field cannot safely represent “payment succeeded but inventory confirmation failed.”

For each transition, record the permitted actor, current state, preconditions, atomic update, external effects, and recovery action. Define invalid transitions as explicitly as valid ones. An event received later is not automatically a newer business fact.

Example invariants include: a reservation cannot allocate more than the available quantity; a transaction cannot fulfill twice; a protected payment operation has one stable business identity; and financial adjustments preserve an attributable history. Tailor the exact rules to the marketplace rather than copying a generic order lifecycle.

Use an atomic conditional update or equivalent concurrency mechanism when checking an expected version and changing state. Reading a version and later writing without a condition leaves a race. Define the retry or conflict response instead of silently overwriting a concurrent decision.

Gate: two simultaneous actors trying to buy the last unit produce the allowed result under a test, not merely in a diagram.

3. Reserve inventory through the authority

The inventory owner defines reservation identity, quantity, expiry, renewal, release, and conversion to a confirmed allocation. A stale search index can suggest an item, but checkout must revalidate price, terms, availability, and authorization through authoritative systems.

Reservation expiry and payment completion can race. Decide what happens if payment succeeds after a reservation expires or a seller rejects availability. Possible responses include reacquiring inventory under current terms, holding the transaction for review, or initiating an approved refund. Do not automatically fulfill unavailable stock.

External inventory feeds need source identifiers, versions where supported, effective timestamps, and a reconciliation policy. Arrival time alone is not a reliable version. If the supplier offers no atomic reservation, state that constraint and design the business promise around it.

Keep the first pilot narrow enough to observe these constraints. Avoid claiming instant guaranteed availability when the upstream system provides only periodic updates.

4. Persist intent and protect each external operation

The transaction service authenticates and authorizes a command, then commits its allowed state change and durable integration intent together where a local transaction supports it. An outbox publisher can deliver that intent later. AWS's transactional outbox pattern explains this local atomic handoff; it does not make the external provider part of the transaction.

"type": "svg-architecture", "title": "Separate durable business intent from provider observations", "nodes": [ ], "links": [ ], "caption": "An accepted command is not a completed payment. The provider call may outlive the application request, and business state advances only after evidence and preconditions are checked." }} />

Scope idempotency to a specific operation and account, retain the request fingerprint, and reject reuse with incompatible parameters. A refund and a capture need different identities even when they belong to the same transaction.

Provider idempotency has a contract and retention horizon. For example, Stripe's idempotent-request documentation describes replayed responses, parameter checks, and key pruning. Preserve the marketplace's operation history beyond whatever provider window your recovery process requires. A new key is not a safe way to bypass an unknown earlier outcome.

Do not mark an external effect complete before calling the provider merely to block duplicates. A crash can leave the effect undone. Record pending, known success, known failure, and unknown outcomes with an owned recovery procedure.

5. Receive events without trusting their arrival order

The payments integration verifies webhook signatures using the provider-required payload handling and secret configuration. It durably accepts a valid event before acknowledging it under the chosen delivery contract, then processes it asynchronously where appropriate.

Signature verification establishes authenticity, not permission to make any business transition. Validate the account context, object identity, expected transaction relationship, amount, currency, and applicable state rule. An event for a real payment must not update an unrelated tenant's transaction.

Handle duplicate events and delayed or reordered delivery. Stripe's webhook documentation documents signature verification, duplicate handling, and the absence of an event-order guarantee. Retain event identity and processing evidence; deduplicating events alone does not deduplicate a business effect triggered by different events.

When observations conflict, retrieve supported authoritative provider state and reconcile against local operation history. A lookup can race with another change, so apply version and transition rules rather than overwriting state blindly. Keep a discrepancy record when evidence remains inconclusive.

6. Reconcile money movement independently of order status

The finance owner defines exact amount representation, currencies, rounding rules, fees, refunds, transfers, disputes, and settlement records. Use currency-aware exact arithmetic appropriate to the provider contract, not binary floating-point calculations for monetary totals.

Link each financial entry to the transaction and provider operation. Preserve corrections as attributable adjustments rather than erasing the previous record. A technical event log is not automatically a compliant accounting ledger; finance must define the required bookkeeping and reporting controls.

Do not assume refunding a buyer reverses a seller transfer. In Stripe's separate charges and transfers model, charge refunds do not automatically change associated transfers. The selected provider arrangement needs an explicit, authorized recovery and reconciliation process, including cases where recovery cannot complete.

A transfer being accepted is also not the same as a bank payout being settled. Keep provider processing, funds availability, transfer, and payout states distinct where the product depends on them. Review payment-method-specific failure and dispute behavior before releasing goods or seller funds.

Gate: the finance owner can trace a sample transaction from charge through adjustments and settlement, explain discrepancies, and identify who may resolve them.

7. Exercise a timeout-and-recovery scenario

Consider an illustrative buyer payment whose provider call times out after the provider accepts it. The application must not announce failure and immediately create a second payment with a new identity.

The integration records the operation as unknown and presents a pending or review state consistent with the product promise. A recovery worker checks provider evidence using the original identity. A delayed webhook may arrive before or after that check; both paths converge through the same protected transition.

If payment succeeded but the inventory reservation expired, the transaction remains an exception. The inventory and operations owners follow the agreed policy. A software rollback cannot restore already sold inventory or undo a completed payment.

"type": "flow", "title": "Resolve an uncertain transaction before repeating its effect", "steps": [ ], "caption": "Recovery is a new authorized action with its own evidence. An inconclusive provider lookup remains unresolved rather than being converted into a convenient success or failure." }} />

Operations tools should expose scoped commands such as retry an eligible integration, approve a refund, or release a reservation. Require the appropriate permissions, reason, and expected state. Avoid a generic “set status” control that bypasses invariants or unaudited database edits.

8. Prove isolation and failure handling

Carry actor, organization, transaction, and operation identity through API requests, background jobs, object storage, exports, and support tools. A tenant identifier supplied by a client is not authorization. Test denied access to another organization's objects as well as successful access to permitted ones.

| Fault test | Required result | Owner | | --- | --- | --- | | Two buyers reserve the final unit | Allowed allocation with an explicit conflict response | Inventory owner | | Crash after local commit | Durable intent is recovered without losing accepted work | Transaction owner | | Timeout after provider accepts payment | Unknown outcome is reconciled without an unguarded repeat | Payments owner | | Duplicate or older webhook | No duplicate effect or invalid state regression | Integration owner | | Refund succeeds but recovery of seller funds fails | Buyer and seller records remain distinct; liability is assigned | Finance owner | | Worker uses the wrong organization context | Operation is denied and evidence is retained | Security owner | | Release rollback occurs mid-transaction | In-flight work retains compatible handling and one executor | Release owner |

Load testing should include hot inventory items and shared downstream limits, not only a large number of independent happy paths. Reconciliation should detect missing operations as well as mismatched totals.

9. Release one observable transaction path

The release owner defines a bounded pilot with approved participants, transaction types, support coverage, and stop conditions. Observe conversion through business states, unknown-outcome age, reservation expiry, fulfillment exceptions, reconciliation backlog, and money-movement discrepancies.

If a release fails, stop new admission or route new operations to the prior compatible version. Preserve in-flight state and event-schema compatibility. Do not replay completed commands or delete records to make the rollback look clean.

Recovery of already executed effects is a separate operation. Refunds, reservation changes, notifications, or payout corrections need their usual authority and audit trail. Expansion depends on reconciled pilot evidence and domain approval, not merely successful checkout screenshots.

Reusable transaction and discrepancy records

| Record | Required fields | | --- | --- | | Transition contract | Current state, command, authorized actor, preconditions, atomic update, effects, recovery | | Operation | Transaction and organization IDs, operation type, request fingerprint, provider account, idempotency key, outcome | | Inventory reservation | Resource, quantity, authority, version, expiry, conversion and release status | | Money movement | Amount, currency, type, provider references, related entries, reconciliation status | | Discrepancy | Conflicting evidence, impact, owner, permitted actions, decision, verification | | Release | Cohort, compatible versions, stop conditions, in-flight handling, evidence and approval |

10. Run an operator tabletop with one disputed order

Create one realistic case in which the buyer sees a charge, the marketplace has an unknown payment result, inventory remains reserved, and the seller has not received a fulfillment instruction. Do not resolve it by directly editing status fields. Give support, payments, inventory and engineering operators the evidence they would normally have and ask them to establish what is known.

The exercise should answer:

1. Which system is authoritative for each fact?
2. Which external operations have confirmed provider references?
3. Could repeating any command create a duplicate effect?
4. What can support communicate without overstating the outcome?
5. Who may release inventory, issue a refund, retry fulfillment or accept financial liability?
6. How will the final resolution reconcile the transaction, ledger and customer communication?

Retain the timeline, evidence consulted, decisions, approvals and final invariants. If participants need production database access to infer the answer, the support model and audit trail are incomplete. If different teams use the same word, such as “paid,” for different facts, correct the domain language before adding automation.

11. Define completion at business-invariant level

Technical delivery is not complete when checkout returns a success screen. Select a bounded set of business invariants and prove them across normal and exceptional paths. Examples include no oversold authoritative inventory, no unlinked provider charge, no duplicated fulfillment command, every money movement associated with an auditable business reason, and every terminal discrepancy assigned to a named owner.

Create a daily pilot reconciliation that compares provider operations, marketplace transaction records, inventory reservations, fulfillment state and financial entries. The comparison should identify missing records as well as unequal values. Every exception needs an age, severity, owner and permitted next action. A shrinking queue is useful evidence; a queue cleared by suppressing exceptions is not.

Before expansion, review at least one release rollback, one delayed external event and one manual support intervention. Confirm that old and new workers cannot both execute the same command without idempotent protection. Confirm that in-flight work remains understandable across the rollback boundary. Confirm that privacy and authorization controls apply to operator tools, exports and logs, not only customer-facing APIs.

The final approval packet should include the state model, operation identities, fault-test results, reconciliation output, support procedure, residual risks and accountable sign-offs. This gives the expansion decision a durable basis and gives future operators a starting point when the real world produces a sequence the design did not predict.

"Commercial roles and payment-method constraints are approved by the relevant owners.", "Each fact and state transition has one authority and an explicit concurrency rule.", "Inventory reservations and financial operations have separate, traceable identities.", "Timeouts, duplicates, reordered events, and crash gaps have tested recovery paths.", "Refund, transfer, payout, and fulfillment states are not collapsed into one status.", "Operator actions and background work enforce organization and object authorization.", "The pilot is reconciled and rollout can stop without erasing in-flight obligations." ]} />

Limitations

This architecture is an engineering framework, not legal, accounting, or payment-provider approval. Provider capabilities, regional availability, and commercial obligations must be checked for the selected arrangement. The relevant business, security, payments, and finance owners must review the design before production use. The examples do not represent a claimed client implementation.