casino callback api: Handle Rollbacks Before Bets Arrive

A casino callback api can deliver a rollback before your wallet has recorded the bet it reverses. A provider may time out, initiate recovery, and send a cancellation while the original request is still delayed. If your handler treats “original not found” as a harmless no-op, a later bet can debit the player after the cancellation has already been accepted. The practical goal is to preserve that cancellation intent and settle both messages according to an agreed contract.

Why arrival order is not transaction order

Callbacks travel through networks, queues, retries, and application workers. Even when a provider sends messages in sequence, your application may process them in a different order.

Consider a stake of 10 account-currency units:

• The provider sends bet transaction B123.
• Your infrastructure delays processing that request.
• The provider times out and sends rollback R456, referencing B123.
• A different worker processes R456 first.
• B123 finally reaches the wallet handler.

Crediting 10 immediately on receipt of R456 would create money if B123 never debited the account. Ignoring R456 could leave an incorrect debit when B123 arrives. Neither outcome is acceptable.

This is a causal-ordering problem, not simply a duplicate-request problem. Remembering that R456 was received does not, by itself, tell the bet handler that B123 must not remain an active debit.

Define the casino callback api rollback contract

Before implementation, obtain written answers for each relevant provider route. Do not assume that every studio behind an aggregator has identical reversal semantics.

Establish identity and scope

Confirm which fields identify the rollback and its original transaction. A round identifier alone is usually insufficient: one round can contain multiple financial events.

Your internal lookup key should include the documented transaction-uniqueness scope, such as provider route, operator tenant, and original transaction ID. Check the referenced player's identity and currency against the original record when available. A matching transaction ID with a different account is a conflict, not permission to move funds.

Also establish whether the message reverses a stake, a payout, or another transaction type. Reversing a payout is not the same accounting operation as cancelling a bet.

Agree on missing-original behavior

Ask the integration team:

• Can a rollback legitimately arrive before its original transaction?
• Must an unknown original receive an error, a retryable response, or a successful cancellation acknowledgement?
• Does success mean that funds were reversed, or that cancellation intent was durably accepted?
• Are partial reversals possible, and how are multiple reversal amounts limited?
• How long can originals and recovery messages arrive late?

Treat the HTTP status and application response code as separate contract elements. A transport-level success may still contain an application error. Do not invent a “pending” response unless the protocol supports it.

Persist cancellation intent without inventing a credit

Use durable state keyed to the original transaction, rather than relying only on a short-lived duplicate cache.

A useful internal model distinguishes:

• Original unseen: no financial posting exists for the referenced transaction.
• Original applied: the original ledger posting committed.
• Cancellation pending original: a valid reversal arrived, but the original is absent.
• Resolved cancelled: the original and cancellation have been resolved with the required net financial effect.
• Conflict: identity, amount, currency, or transaction-type checks failed.

These are internal states, not suggested provider response codes.

For a full bet cancellation, a valid rollback against an unseen original should not create an available-balance credit. Where the provider contract permits it, store a cancellation marker—sometimes called a tombstone—and acknowledge only after that marker commits durably.

If the contract instead requires an unknown-transaction error, return that response. You may still preserve the event for investigation, but do not silently turn a rejected cancellation into an accepted one. Agree on the late-original recovery behavior before launch.

Resolve a late original atomically

When B123 eventually arrives, its handler must inspect cancellation state within the same protected operation that decides whether to post the debit.

Depending on the agreed accounting model, resolution might record the original as cancelled without a balance movement, or create linked debit and reversal entries with zero net effect. If using paired entries, commit them atomically so no temporary debit becomes available to another wallet operation.

The response to B123 must match the provider contract. Do not return an ordinary successful-bet response merely because the final balance is correct; that response might incorrectly leave the provider's round state active.

Protect the transition, not just the endpoint

Separate bet and rollback handlers can each be correct in isolation and still fail when executed concurrently.

Serialize decisions for the same original transaction using a suitable database lock, serializable transaction, or equivalent concurrency mechanism. Because the original row may not exist yet, locking only existing bet rows is insufficient. One option is a uniquely keyed coordination record that both handlers create or lock before inspecting state.

Within that boundary:

1. Validate the current transaction state.
2. Apply any permitted financial entries.
3. Update the original-to-reversal relationship.
4. Persist the processing result needed for recovery.
5. Commit before sending a success response.

Authentication and request validation must happen before accepting cancellation intent. An unauthenticated rollback must not be able to block a future legitimate bet.

If a worker crashes after commit but before responding, the retry should find committed state and avoid another financial effect. Return the response required by the contract; this may require reconstructing a current balance rather than replaying an old response body.

Build an acceptance test around message permutations

A sandbox test that sends bet, then rollback, proves only the simplest path. Ask for controlled replay or build a harness around the documented callback format.

Minimum test cases

• Rollback first, original later: no unsupported credit appears; the final net effect matches cancellation semantics.
• Original first, rollback later: the original posting is reversed once.
• Both at once: repeated concurrent runs produce the same valid ledger outcome.
• Repeated rollback: retries do not generate additional reversals.
• Different rollback IDs, same original: a full reversal cannot exceed the original posting.
• Original never arrives: cancellation intent remains traceable without changing the player's funds.
• Mismatched player or currency: processing stops without a financial effect and raises a reviewable conflict.
• Crash after commit: retry handling recovers the committed result without reposting.

If partial reversals are supported, add tests for cumulative limits and overlapping requests. Do not apply a full-cancellation state model unchanged to partial reversals.

For every test, capture the request identifiers, authentication outcome, state transitions, ledger entry references, response code, and final balance. Redact credentials and unnecessary player data. A screenshot of the balance alone does not prove correct processing.

Give unresolved cancellations an operational owner

Create a reconciliation queue for accepted cancellations whose originals remain unseen. Assign ownership to wallet operations or the integration support team, with engineering escalation for state conflicts.

Record the first-seen time, provider route, original reference, reversal reference, and latest investigation result. Monitor queue age and recurring patterns by route. Use timing thresholds derived from the provider's retry and recovery windows rather than an arbitrary universal timeout.

Do not automatically delete cancellation markers when a cache expires. A late original could then become an active debit. Retention must account for supported recovery windows, audit obligations, and data-minimization requirements. If detailed records are archived, ensure late-message handling can still access the cancellation decision or safely reject processing for review.

Put the decision into integration sign-off

For a GamingAPI evaluation, start with the docs and ask for the applicable rollback rules for your selected routes. GamingAPI offers 16,000+ games from 150+ studios through one API with a seamless wallet, but catalog breadth does not replace transaction-level acceptance testing.

Use contact to confirm unresolved protocol questions before production. Sign-off should include approved message permutations, documented response behavior, reconciliation ownership, and evidence that concurrent delivery cannot leave an accepted full cancellation as a lasting debit.

FAQ

Should an unknown rollback immediately credit the player?

No. A credit without evidence of an original debit can inflate the balance. Follow the missing-original contract and preserve accepted cancellation intent durably.

Can we use the round ID as the reversal key?

Only if the contract explicitly makes it sufficient. Rounds may contain several transactions, so reversal matching normally needs the original transaction reference and its uniqueness scope.

How long should cancellation markers remain available?

Base retention on documented late-delivery and recovery windows, applicable obligations, and archival design. Do not remove a marker while a valid late original could still be processed without consulting it.