An API client may send a request, receive a timeout and retry without knowing whether the first operation committed. A game aggregator or event broker can likewise deliver the same callback again. In a casino platform, treating either repetition as a fresh debit, credit, rollback or reward can produce real financial discrepancies. The correct design distinguishes message delivery from a business transaction and makes each financial effect durable exactly once within the operator's own ledger. Different vendors specify different transaction identities, duplicate response codes and retry rules, so there is no universal callback contract. This guide builds a practical model for authenticated intake, atomic posting, safe replies, out-of-order recovery, reconciliation and operational testing. [1] [2] [4]
Published
Repeated delivery can be normal; the operator must prevent repeated financial effects.
On this page
Why do APIs send the same callback more than once?
A sender can lose the HTTP response even after its receiver completes the transaction. It then retries, or a queue re-delivers a message whose acknowledgment was not recorded. At-least-once delivery explicitly allows repeated messages, and default message order is not guaranteed. A duplicate delivery is not automatically fraud or a second business transaction. [4] [5]
In a casino, a single wallet debit, credit or reversal must not be executed twice because it arrived twice. The business effect, callback receipt and response delivery have different life cycles. Vendor wallet APIs such as St8 and 7SoftTech use transaction identifiers to define repeated operations; their precise responses and edge cases differ. [1] [2]
Which identifiers belong in an idempotency key?
Separate the delivery attempt ID, authenticated provider identity, business transaction ID, operation type, referenced original transaction and game round. Only the agreed business identity should prevent repeat financial postings. Scope a vendor transaction ID according to its documented uniqueness; never assume that IDs from unrelated providers or tenants share one global namespace. [1] [2] [3]
Identifier
Role
Design rule
Provider / tenant
Defines origin namespace
Enforce authenticated ownership
Transaction ID
Identifies business movement
Unique within contract scope
Operation type
Debit, credit or reverse
Honor vendor identity rules
Delivery / event ID
Identifies one notification
Not always the wallet key
Original transaction ID
Links reversal to prior effect
Verify relation before reversal
Round and player ID
Supplies transaction context
Never replace transaction identity
An idempotency key is meaningful only with a stable payload fingerprint and state. If the same business ID arrives with a different amount, currency or player, it is a conflict requiring a contract-defined error or review, not permission to post another movement. AWS describes the same-intent principle for retry-safe APIs. [3] [4]
What must a callback receiver verify before deduplication?
Verify the provider's configured signature or other authentication proof using the exact expected input before trusting a transaction ID. Then authorize the source for the operator, player wallet, currency, action and relevant session. A known ID in an unauthenticated message cannot prove that an operation was already completed. OWASP recommends validating webhook authenticity before handling duplicates. [1] [6]
Verify signature, time window and replay controls using the specific provider's protocol.
Check the provider/tenant and map the player to the intended internal wallet and currency.
Validate transaction identity, amount precision, action and referenced parent transaction.
Compare the received payload with the stored fingerprint before returning a duplicate result.
Keep authentication metadata, business identity and safe request hashes for tracing, while excluding secrets and unnecessary personal data from logs. An HTTP 200 acknowledgment must not be issued for a forged request merely because its transaction ID resembles a processed one. [2] [6]
What is the end-to-end retry-safe callback flow?
After authentication, the operator looks up or claims a unique business key, checks the payload, applies the wallet mutation and records the outcome as one durable database operation. A repeat with the same accepted identity retrieves the stored result instead of changing the wallet again. If the initial outcome is unknown, it enters a reconciliation path. [1] [4] [6]
Authenticate the incoming callback and resolve its authorized player and provider scope.
Derive the contracted business key and validate the original operation or reversal reference.
Atomically reserve or find the transaction, perform any permitted ledger mutation and store its result.
Send a provider-specific response; reconcile uncertain transactions without inventing a second effect.
⊕View largerSeveral delivery attempts may refer to one durable transaction and its stored outcome.
The database commit and the outbound HTTP response cannot generally be made one atomic operation across two systems. Design for the failure in which the commit succeeds but the reply is lost; that is exactly when the sender will retry an already completed movement. [4] [7]
How can a database enforce one financial effect?
Use an enforced unique business-key constraint and perform the receipt registration, balance or ledger posting and final result recording under an appropriate transaction boundary. A preliminary SELECT followed by a separate UPDATE is not sufficient under concurrency: two workers can both observe an absent key. Database uniqueness and locking must remain authoritative. [3] [4]
Observed state
Safe processing
Failure case to test
Unseen valid key
Commit effect and outcome once
Parallel first deliveries
Completed same payload
Read stored decision
Second credit not posted
In progress
Wait, retry or reconcile safely
Competing workers
Same key, changed payload
Reject and raise conflict
Amount or player mismatch
Rolled back before commit
Permit controlled retry
Crash after key reservation
A durable event inbox can help, but a queued receipt is not proof that money was posted. Keep an explicit transaction lifecycle, ledger reference and immutable result. Decide whether a reversal creates its own identified movement or transitions a linked operation according to the actual provider specification. [1] [3]
What should an API return for duplicates and conflicting retries?
For an authenticated duplicate that has been durably handled, return the original successful outcome or the precise duplicate code expected by that integration. There is no universal rule that every casino provider accepts HTTP 200, error 409 or a specific JSON status. St8, 7SoftTech and GR8 Tech document different field names and business error semantics. [1] [2] [3]
Keep a stable response contract for the same transaction identity and unchanged request meaning.
Reject the same ID with contradictory player, amount, currency or operation details.
Treat a lost HTTP response after commit as a successful prior effect, not a fresh operation.
Distinguish business rejection from transient technical failure so the sender stops or retries correctly.
Do not blindly replay a balance snapshot if the provider expects the current balance, and do not invent a duplicate code absent from its contract. Verify how each provider handles replays, reversals and whether a failed business action may be retried with the same ID. HTTP method semantics alone do not make an arbitrary POST safe. [2] [3] [7]
When should callers retry, back off or stop?
Retries should follow the operation's idempotency contract and the known type of failure. Network timeouts and some transient server errors can leave the outcome uncertain. Invalid signatures, malformed requests and final business declines must not be retried endlessly. Use bounded attempts, backoff with jitter and a reconciliation path instead of aggressive duplicate traffic. [4] [6] [7]
Condition
Preferred action
Reason
Timeout after send
Query or retry same identity
Prior commit is unknown
Transient 5xx / rate limit
Bounded contract-aware retry
Temporary capacity or failure
Invalid signature
Reject and alert
Unauthenticated request
Final business decline
Stop per vendor semantics
Retry cannot change policy
ACK lost after commit
Resolve stored outcome
Prevent second posting
Separate the sender's retry queue from manual repair operations. An operator should know which callbacks can be safely replayed, which require status inspection, and which must be escalated. Never change a business transaction ID merely to force an uncertain transfer through again. [3] [4]
What if callbacks arrive out of order?
An event broker may deliver messages out of order, and a game provider's cancel or rollback can overtake the original debit. Some vendor contracts require retaining a reversal marker so a later original bet cannot be posted after it has already been canceled. Other APIs specify a different lifecycle, so do not generalize one vendor's error codes to all integrations. [1] [2] [5]
Persist the original-operation reference and the current transaction state, not merely an arrival timestamp.
Define which debit, credit, cancel and adjustment transitions are allowed for each vendor.
Preserve a durable reversal marker when the contract permits cancellation before the original arrives.
Hold unresolvable references for reconciliation rather than synthesizing wallet movements.
Arrival order is not the same as business order. Never sort ledger effects solely by request timestamp from a remote client. Use transaction identity, operation dependencies and authoritative provider or operator state to decide what can commit. [2] [5]
How are retries reconciled and monitored after outages?
A callback can be authenticated and received but still fail to commit, or commit yet fail to be acknowledged. Monitor both technical delivery status and business posting state. Reconcile unresolved keys against the operator ledger and provider records, with explicit procedures for conflicting data. This is distinct from merely refreshing a player balance in the UI. [1] [3] [4]
Track attempts, accepted duplicates, signature failures, payload conflicts and reconciliation backlog per provider.
Alert on repeated timeouts, stalled in-progress keys, reversal-before-original cases and discrepancies.
Provide a restricted manual replay that retains original identifiers and an operator audit reason.
Compare ledger records and provider transaction histories before considering compensating entries.
Test retention windows for dedup records against the longest contractual retry and dispute periods.
Avoid storing raw payment or identity payloads in general analytics. Record hashes, safe correlation IDs, timestamps, status changes and operator actions with suitable retention and access restrictions. A clean dashboard should distinguish duplicate delivery volume from actual financial imbalance. [4] [6]
Which acceptance tests prove retry safety?
A passing happy-path bet and win do not prove that retries are safe. Certification should exercise duplicate transaction IDs, conflicting payloads, concurrent workers, missing acknowledgments, reversals and delayed messages under the actual provider contract. 7SoftTech explicitly documents wallet certification examples for repeat bet, win and cancel callbacks. [2]
Post one debit or credit, replay the exact same signed callback, and verify only one ledger effect.
Send the same business ID with another amount, player or currency and verify a controlled conflict.
Race two valid deliveries, crash after a simulated commit, and check durable response recovery.
Deliver a cancel before its referenced original and verify the vendor-specific state rule.
Disconnect the provider, replay delayed messages, reconcile ledger totals and inspect audit evidence.
Before release, confirm the response matrix, uniqueness scope, retry horizon and reversal handling with each integration partner. The final acceptance criterion is not zero duplicate messages; it is that every authorized business movement has the correct effect once, even when transports retry, replies vanish and events arrive in unexpected order. [1] [3] [4]