Book Seller · Tier 3
Relevant Tangents and Sharp Edges
These issues sit beside the main architecture and frequently decide whether the design remains correct under real payment, inventory, and retry behavior.
Payment authorization and capture
- Authorization reserves funds with the card issuer. Money remains uncaptured.
- Seller confirmation means the seller commits to fulfill the held inventory.
- Capture finalizes the charge and transfers funds according to the processor configuration.
- Manual capture allows the sequence: hold inventory → authorize funds → seller confirms → capture.
- A captured payment with no seller confirmation triggers refund or reversal and an auditable failure state.
SCA and 3-D Secure
Some payments require customer interaction. The client confirms the PaymentIntent and completes any challenge before asynchronous fulfillment enters the capture-ready state. This keeps the interactive challenge in the user session and preserves the fulfillment time budget.
Webhook role
- Stripe webhooks report payment state; they do not prove inventory fulfillment.
- Seller callbacks report seller state; they do not authorize payment transitions by themselves.
- Handlers verify signatures and timestamps, deduplicate event IDs, and signal the owning order workflow.
- The workflow applies events only when the current state permits the transition.
Seller credential storage
- Store non-secret endpoint and scope metadata in the seller database.
- Store client secrets, private keys, certificates, and refresh tokens in a managed secret vault.
- Mint short-lived access tokens on demand and keep them in memory with expiry skew.
- Protect seller callbacks with HMAC or asymmetric signatures, timestamp and nonce checks, and per-seller sequence numbers where ordering is significant.
Inventory outside the platform
Sellers may sell the same stock through their own websites. A platform cache can show five copies while the seller has already sold them elsewhere. The practical response is a real-time seller hold for five to ten minutes. The hold result, price, and expiry override cached availability.
Late seller listings
A seller may publish a matching book after a buyer request entered the system. Source discussions expose two product choices: close the request against the candidate set available at processing time, or keep unmatched requests active and rematch them when new inventory arrives. The latter changes the system into a standing-order marketplace.
Fairness and hot keys
- Partitioning by ISBN preserves first-come ordering for scarce books.
- Popular books concentrate traffic in one partition.
- Partitioning by order ID spreads load and delegates oversell prevention to the hold API.
- Appending random suffixes splits a hot book across partitions and sacrifices one total order.
- The product must choose fairness, highest bid, or throughput before selecting the queue key.
Failure ledger
| Failure | Compensation |
|---|---|
| No seller below maximum | Cancel payment authorization and mark failed. |
| Hold succeeds, authorization fails | Release hold or wait for expiry. |
| Authorization succeeds, seller rejects | Void authorization, release hold, try next seller. |
| Seller confirms, capture fails | Retry idempotently; cancel or escalate before shipment. |
| Capture succeeds, seller reneges | Refund, mark refunded, penalize seller, notify buyer. |
| Worker disappears | Queue visibility timeout or durable workflow retry resumes the same state. |
Operational signals
- Per-seller latency, success rate, 429 rate, and circuit state
- Order age by workflow state
- Hold expiry margin and compensation backlog
- Authorization, capture, cancellation, and refund failures
- Queue age, hot partitions, and repeated delivery count
- Offer freshness and final-hold rejection rate