Sportsbook Platform Architecture: Bets, Wallets and Settlement

A sportsbook architecture is credible when it can explain a bet after an inconvenient failure. The provider accepted it, but the response was lost. Funds were reserved, but the wallet confirmation arrived late. A winning result was credited, then corrected. None of those situations can be resolved reliably by looking at one status field.

The central design problem is to keep three records consistent over time: what the operator accepted, what happened to the customer's money and which result was applied. This guide develops a state model and a concrete ticket walkthrough for product, engineering and operations teams. It assumes fixed-odds betting with an account wallet; exchanges, pooled betting and credit arrangements need different financial rules.

Assign authority before separating services

Separate logical responsibilities first. The offer component owns the current market and outcome availability. The acceptance component owns the ticket decision and its accepted terms. The wallet owns reservations and posted money movements. Trading owns the admission limits and exposure model. Settlement owns the application of result evidence under the relevant rules. Support can inspect their combined history but should not become an alternative writer of financial state.

These components do not all need separate deployments or databases. A modular application can keep closely coupled ticket and wallet changes in one local transaction. Separate services become useful when ownership, independent scaling or failure isolation justify the additional protocols. Drawing an arrow between two services does not make their writes atomic.

With an external trading or acceptance supplier, name the decision it actually owns. Receiving an odds message is not proof that the supplier accepted a ticket. Record its request identity, final ticket identity and decision evidence through an adapter. Product boundaries belong in the sportsbook product scope; the engineering work at supplier boundaries is discussed in platform integration services.

Give the bet, its funds and its result separate states

Use separate state axes, with names chosen for your actual implementation:

• Placement: received, pending decision, accepted or rejected. A communication timeout describes uncertainty about this decision; it does not establish rejection.
• Funding: not reserved, reserved, committed or released. A reservation reduces spendable funds. Committing it records the stake as paid; it must not charge the stake a second time. Releasing an uncommitted hold is different from refunding a paid stake, which needs another money operation.
• Settlement: awaiting evidence, ready to apply, applied or awaiting correction. The settlement record points to the evidence, rules and financial operation that produced it.

Define valid combinations as well as transitions. Set a resolution deadline for pending work, but do not turn it into automatic rejection or release unless the authoritative contract proves no accepted ticket remains. Accepted with reserved funds may be a recoverable intermediate state when an external acceptance decision is known but the wallet commitment has not yet been confirmed. Accepted with released funds is an exception requiring investigation, not a normal completed journey. Mark a settlement applied only after its monetary operation is confirmed; until then, keep the intended result and pending operation visible. Its record should refer to the committed stake and the particular result application.

Retain the original selection parameters, accepted price, stake, currency and rule reference. The current market can close or disappear without changing those terms. Keep a local ticket version for guarded updates, plus separate identifiers for requests, provider messages and money operations. One shared identifier for everything cannot express several legitimate corrections to the same ticket.

Walk one ticket through the allowed transitions

Consider hypothetical ticket B71: a customer starts with 100 currency units and places a single for 20 at decimal odds of 3.00. Assume no taxes, fees, bonuses or cash-out. Here is a review worksheet expressed as transitions rather than a feature list:

1. Receive: persist the caller's request identity and its immutable placement parameters. Bind duplicate detection to the intended customer and operator scope. A changed stake under the same identity is a conflict; a deliberate second bet needs a new identity.
2. Reserve: secure 20 through the wallet's concurrency controls and reserve the required risk capacity. Under a model where holds do not alter the posted balance, the posted balance remains 100 and available funds become 80. Persist the pending supplier command before sending it.
3. Accept: record the authoritative acceptance and the exact accepted terms. Committing the existing reservation makes the posted balance 80, with no remaining hold and available funds still 80. In one database this can be atomic; across systems, keep the known acceptance and retry the same wallet commitment until its status is resolved.
4. Reject instead: a definitive rejection before acceptance releases the reservation and pending risk capacity. Both posted and available funds return to 100. A lost response alone is not sufficient evidence for this transition.
5. Settle: after acceptance, apply an authorised winning result to the committed stake. The gross return is 20 × 3.00 = 60, including the stake, so the posted balance becomes 140. Apply that financial operation once even if the result is redelivered.
6. Correct: if authorised evidence changes that win to a loss under the applicable rules, reverse the 60 credit through a linked operation. The posted balance becomes 80. Do not deduct another 20: the original stake was already paid.

The rejection is an alternative branch, not a step after acceptance. The figures show a hold model, not a universal wallet API. A different wallet may represent the reservation differently; the spendable amount and final financial effect must still agree. Each transition needs a guard, an authorised writer, a durable record and a defined action if confirmation is missing.

Close the gap between a database commit and an event

Checking a balance and later updating it is not sufficient concurrency control. MySQL's locking-read documentation explains why a plain read does not protect related writes. Within a local transaction, use suitable guarded updates or locks and uniqueness constraints to protect the actual money and ticket invariants. Keep transactions short; a network call to a provider should not hold a wallet row locked while waiting indefinitely.

The next gap is publication: a ticket commits, then the process dies before telling downstream services. Write the ticket change and an outbound event record in the same local transaction, then publish committed records separately. The transactional outbox pattern documents this approach and its need for duplicate-tolerant consumers.

For B71, make the outbound fact specific: acceptance occurred, with the ticket version and accepted terms. A relay restart may publish it again. If the wallet is a separate system, that event or a durable command can request commitment of the existing reservation using a stable money-operation identity. The wallet must record duplicate detection together with the financial effect; recording “processed” before the effect, or afterwards in an unrelated transaction, leaves another failure gap.

An outbox does not make the remote wallet and ticket database one transaction. Keep incomplete hand-offs visible, retry within the agreed contract and reconcile their outcomes. The application should be able to answer whether B71 is accepted and funded even when its notification email or reporting projection has not caught up.

Make settlement a sequence of accountable operations

Separate sports-result ingestion from ticket settlement. A provider reports facts about an event, market or outcome; the settlement component maps them to accepted tickets and applies the appropriate rules. It needs the original market parameters, not merely the market's display name. Results arriving before a delayed acceptance confirmation should be retained and correlated rather than discarded because the local ticket is still pending.

Use an operation identity fine-grained enough to distinguish the result application from its correction. It may incorporate a local ticket and settlement revision, while preserving the supplier's evidence and identifiers separately. The precise scheme depends on the provider contract. Do not assume a message timestamp is a universal, globally ordered revision number.

Corrections are part of the model. For example, Sportradar's UOF rollback documentation describes undoing an erroneous settlement, including at outcome level. Record the original application, authorised reversal and any replacement; keep the current display status as a view of that history. For B71, repeated delivery of the same reversal must not remove another 60.

If the customer's credited funds were spent or withdrawn before correction, the simple walkthrough no longer describes their current balance. Resolve the discrepancy through the operator's approved account policy and case process. Do not delete the original entry or hide a deficit by changing the displayed balance.

Engineering cannot invent the betting rules. In Great Britain, the Gambling Commission's published-rules guidance covers acceptance and settlement rules, including voids, errors and result determination. Use it within its jurisdiction; agree the actual applicable requirements with the operator and qualified advisers. The wider ledger model is covered in wallet and transaction-ledger design.

Scale the offer without weakening the money path

Offer browsing and authoritative placement have different consistency needs. An odds catalogue can use cached read models to serve many visitors. Acceptance must evaluate the relevant current offer state, customer eligibility, funds and risk controls at its authoritative decision point. A fast stale catalogue is not an authority to accept a suspended selection.

Partition processing around real contention: a customer's money, a ticket's transitions, or the exposure bucket that limits a particular risk. A queue key can help preserve processing order within a scope, but correctness still depends on guarded writes and the actual provider's ordering rules. Avoid a single global queue that makes one busy match delay unrelated work. Also avoid treating every event from different producers as comparable merely because it has a timestamp.

Feed recovery and ticket recovery need distinct evidence. UOF recovery documentation explains that recovery may deliver current odds instead of every intermediate change, and may combine settlement messages. Rebuilding the catalogue is not a way to reconstruct B71's accepted price or financial history.

During a live-event incident, close new admission in the affected scope when its data or controls cannot support a valid decision. Keep accepted-ticket processing, status lookup and financial reconciliation operating where their dependencies allow it. Reopening requires the recovery and local application conditions defined for that integration. Load tests should include a busy event, a slow provider and a settlement burst, not just anonymous page views. See scaling for peak traffic and live events for the capacity discussion.

Review the architecture through recoverable incidents

Review the architecture by deliberately interrupting B71 between its durable steps. Kill the process after a reservation, after external acceptance, after the ticket commit and after a wallet credit. For each interruption, identify the records that remain and the component allowed to continue. If the answer is “support changes the status until it looks right”, the recovery design is unfinished.

A retry contract must say what identity survives, what happens when parameters differ and how late requests are recognised. The Amazon Builders' Library discussion of idempotent APIs examines caller-provided request identifiers, parameter conflicts and late arrivals. For a sportsbook, set retention against actual provider and operational recovery needs; expiry of a short-lived cache must not recreate a settled bet.

Build an operational view that joins the ticket, reservation, stake commitment, result evidence, settlement operations and last confirmed provider status. Highlight impossible combinations and work that has exceeded its agreed resolution window. An operator action should invoke a permitted command with recorded authority and reason, not update several status columns by hand.

Before extracting more services, prove the four checks below and measure the unresolved work they reveal. A small system with a durable recovery path is a stronger starting point than many services whose partial failures cannot be explained. For the supplier-side implementation, continue with integration-layer boundaries and adapters.

Two extensions need their own boundaries. In a multi-brand platform, make the operator and wallet scope explicit in tickets, configuration and request identities; do not let one brand's control action affect another unintentionally. If the product also contains a virtual economy, define its currency and reward rules separately. A shared account interface is not a reason to treat virtual rewards as interchangeable with sportsbook funds.

• Interrupt acceptance after the provider decides but before the local response is saved. Recover the same request and prove that the known ticket, its reserved funds and its eventual stake commitment agree, with no second bet.
• Commit a ticket and stop the event relay before publication; then stop it again after publication but before acknowledgement. Prove eventual delivery without duplicate stake commitment or another financial effect.
• Apply a result, replay it, then authorise a correction and replay that correction. Reconcile the exact net movement and preserve all linked operations; demonstrate the controlled path when funds have already been spent.
• Rebuild read models and recover feed messages while tickets are pending and outcomes are arriving. Prove that accepted terms and ledger history survive, that unapplied legitimate outcomes are retained and that only eligible offers reopen.