Sportsbook API Integration: Settlement and Resettlement

A sportsbook API integration is not finished when a player can place a bet. The harder work starts when acceptance times out, settlement arrives twice, or a result changes after winnings have reached the wallet.

For operators adding sports betting alongside casino games, familiar wallet patterns help, but they are not enough. Sports betting introduces long-lived liabilities, partial outcomes, cash-outs, and result corrections that can cross reporting periods.

This guide focuses on one practical goal: making settlement and resettlement safe before launch. It assumes the operator controls the player wallet and integrates with an external sportsbook platform. Exact responsibilities depend on the supplier contract and API model.

Define the settlement contract before coding

Do not begin with endpoint names. Begin with a written agreement about what each financial message means.

Ask the sportsbook supplier to specify:

• Whether bet acceptance reserves funds or immediately debits the stake.
• Whether settlement amounts include the returned stake.
• Whether corrections contain replacement totals or incremental adjustments.
• Which identifiers uniquely identify bets, financial events, and revisions.
• Whether cash-out closes the entire bet or only part of it.
• How voids, pushes, dead heats, and partial settlements are represented.
• How an operator retrieves authoritative state after missing a callback.

These details determine your ledger design. A field named `win_amount` is not a sufficient contract: it might mean profit, gross return, or a promotional payout with different withdrawal treatment.

Choose one accounting model per flow

Under a stake-debit model, a 100-unit bet removes 100 units at acceptance. A winning settlement at decimal odds of 2.50 then credits a gross return of 250 units.

Under a reservation model, acceptance first moves funds from available to reserved. A later action consumes or releases that reservation according to the agreed workflow.

Both approaches can work. Mixing them can deduct a stake twice or return money that was never taken. Document the journal entries for every outcome before implementation.

Keep bet state separate from money movement

A bet status describes the wagering lifecycle. A wallet transaction describes a financial effect. They should be linked, not treated as the same record.

An illustrative lifecycle might include:

• `pending_acceptance`: the placement request exists, but acceptance is unresolved.
• `accepted`: the supplier has confirmed the wager.
• `rejected`: the supplier declined it.
• `partially_settled`: some components have settled while others remain open.
• `settled`: the current result has been applied.
• `resettled`: a correction has replaced an earlier result.

These labels are examples, not a universal sportsbook standard. Map the supplier's actual states explicitly, including cash-out and cancellation behavior.

A timeout must not automatically become a rejection. The supplier may have accepted the wager while its response was lost. Keep the placement unresolved until a status lookup or documented recovery procedure establishes the outcome.

For each bet, retain the operator request ID, supplier bet ID, player account, currency, stake, accepted odds, timestamps, and current settlement revision. Store financial events separately so an auditor can reconstruct every balance change.

Make wallet effects idempotent

Callbacks will sometimes be retried. Your integration must be able to receive the same instruction repeatedly without applying its financial effect repeatedly.

Use durable event identity

Agree on a supplier event identifier and its uniqueness scope. A robust deduplication key may combine supplier, tenant, wallet, and financial event ID. Do not assume a bet ID is enough: one bet can legitimately generate several financial events.

For each incoming event:

1. Authenticate the sender and validate the payload.
2. Check the event identity and previously stored processing result.
3. Validate currency, amount precision, account mapping, and revision rules.
4. Write the ledger effect and processing record atomically.
5. Return the acknowledgement required by the supplier contract.

If a duplicate has the same identity but different financial content, quarantine it for investigation instead of silently accepting it.

Atomicity matters. If the wallet is credited but the deduplication record is not saved, a retry can credit it again. Where services cannot share a database transaction, use a durable workflow with idempotent downstream commands and recovery states.

Handle ordering explicitly

A correction can arrive before an earlier settlement callback. Arrival time is not business order.

Use documented revision numbers or sequencing rules where available. Otherwise, retrieve authoritative settlement state and reconcile against it. Do not discard every late message merely because its timestamp is older; it may represent a separate, still-unapplied financial action.

Treat resettlement as an auditable correction

Resettlement is a change to a previously applied outcome. It should not erase history or overwrite the original wallet entry.

Consider the stake-debit example:

• Acceptance debits 100 units.
• Revision 1 declares a win and credits 250 units.
• Revision 2 changes the outcome to a loss, with a replacement gross return of zero.

The correction is minus 250 units, not minus 350. The stake was already deducted at acceptance.

If the supplier sends replacement totals, calculate the adjustment against the previously applied entitlement for the same settlement scope. If it sends deltas, apply the documented delta once. Never infer the message type from whether an amount is positive or negative.

Keep references from each correction to its bet, superseded revision, source event, and ledger entries. Separate cash stake, bonus stake, and promotional winnings where their rules differ.

Decide what happens when funds are unavailable

A player may spend or withdraw winnings before a correction arrives. Define this scenario with finance, compliance, legal, and the supplier before launch.

The policy should establish whether account-level negative balances are supported, how disputed adjustments are recorded, who absorbs unrecoverable amounts, and what communication is required. Any account or withdrawal restrictions must follow applicable law and published terms, not an improvised support decision.

Do not silently debit an unrelated currency or convert a cash liability into a bonus adjustment.

Build a go-live test pack around failure

A happy-path demo proves very little about settlement safety. Require documented expected balances and journal entries for each acceptance test.

Include at least these cases:

• Placement accepted remotely, but the response times out locally.
• The same settlement callback is delivered repeatedly.
• A process crashes after receiving an event but before acknowledgement.
• Two workers process the same financial event concurrently.
• A corrected result arrives before the original settlement.
• A settled win becomes a loss after the player spends the return.
• A void returns the correct stake under the chosen accounting model.
• A partial cash-out is followed by settlement of the remaining position.
• A promotional bet settles without incorrectly returning a nonreturnable stake.
• An event contains an unsupported currency or invalid precision.

For each case, verify not only the balance but also the bet state, audit trail, retry behavior, and operational alert. Use integer minor units or suitable fixed-precision decimals, never binary floating-point arithmetic for money.

Give operations a recovery path

Webhooks should not be your only source of financial truth. Agree on a reconciliation mechanism, such as a transaction feed, settlement export, or authoritative lookup API.

Compare supplier records against accepted bets, applied returns, corrections, and wallet journals. Distinguish genuinely missing entries from events still inside the expected delivery window.

Create alerts for unresolved placements, rejected callbacks, revision conflicts, and reconciliation differences. Assign an owner and a safe remediation procedure to each alert. Manual adjustments should require authorization and leave an audit trail; editing database balances is not a recovery procedure.

GamingAPI's casino aggregation scope should not be mistaken for confirmation of sportsbook functionality. If you are planning a combined casino and sports product, contact the team to discuss casino integration boundaries and identify the sportsbook capabilities that require separate verification.

FAQ

Can a casino wallet also support sportsbook bets?

Potentially, but the integration must support the sportsbook's reservation or debit model, long-lived bets, partial outcomes, and corrections. A shared balance alone does not establish compatibility.

Should we reverse the original settlement before applying a correction?

That depends on the contract and ledger design. Reversal-and-replacement and net-adjustment approaches can both work, provided they preserve history, apply once, and cannot leave an unintended intermediate balance exposed.

When is a bet settlement final?

There is no universal technical cutoff. Confirm the supplier's correction windows, sport-specific rules, and contractual responsibilities, then align player terms, reporting, and operational procedures with those requirements.