An iGaming Integration Layer That Preserves Meaning Across Providers

A provider returns “success”, but the platform has not credited the wallet. An identity review is complete, but an account restriction still applies. A game round has ended, but a financial correction is outstanding. If an integration layer compresses these conditions into one status, it can hide the very information the operator needs to recover.

For architects, product owners and integration leads, the goal is to protect the platform's own decisions while retaining the meaning of external evidence. Adapters should isolate provider-specific protocols; they should not pretend all games, payments and verification services behave alike. This guide explains the boundary, follows an uncertain payment and gives a concrete set of checks for delivery and provider replacement. Its workflows are design examples, not reports of a deployed system.

Keep product authority out of provider adapters

Draw three responsibilities before choosing a deployment. The provider performs its contracted external service. The adapter authenticates communication, translates requests and results, and preserves references needed to explain them. The platform domain decides what that evidence permits: a wallet posting, a game-session transition or a scoped verification decision.

Microsoft's anti-corruption-layer pattern describes protecting one system's model by translating another system's semantics. It can be an application component or a separate service; the added boundary still needs consistency, monitoring and maintenance. Separate deployment is justified by ownership, release, scaling or isolation needs, not by the presence of an external API alone.

Keep balance authority with the wallet, account restrictions with their owning domain and product eligibility with the approved policy. The adapter can explain a provider result; it should not bypass those authorities by updating their tables. Use the platform architecture guide for those decisions and platform integration services for the implementation scope. A shared integration layer does not need to become a new owner of every business workflow.

Use shared models without flattening different outcomes

A canonical model is the platform's stable vocabulary for a particular domain. Prefer separate payment, game and verification models over a universal “transaction” with a success flag. Share genuinely common transport tooling, but preserve differences that change the next allowed action.

• Payments: distinguish the player request, provider attempt, external processing outcome, wallet application and reconciliation. Provider acceptance is not automatically the evidence required to release a credit.
• Games: retain session, round and provider-operation identities, their financial effects and any later correction. A round identifier alone may cover several legitimate operations; deduplicating solely by round can suppress valid results.
• Verification: retain the case, attempt, evidence version, check scope and review outcome separately from current account permissions. An earlier approved review must not clear a newer unrelated restriction.

KYC means know your customer; this example concerns external verification evidence within that wider process. Sumsub's verification webhook documentation distinguishes review states and notes that configured workflows affect when a reviewed event is sent. This is a provider-specific example of why “callback received” cannot mean “player eligible”. Translate the selected product's actual semantics; the KYC workflow guide covers the subsequent decision.

For each mapped outcome, record the source field, internal meaning, permitted transition and treatment of a missing or unsupported value. Keep useful provider references and adapter-version evidence. Route an unknown consequential state for investigation instead of guessing success or failure; harmless extra fields need not break an otherwise compatible payload.

Keep a timed-out request attached to its original intent

Consider a hypothetical deposit. The platform records the player's intent and a provider attempt before making the external request. The provider accepts it, but the response is lost. The correct local conclusion is “outcome unresolved”, not “provider rejected”. Starting a new attempt elsewhere may create an additional charge.

AWS's guidance on idempotent APIs explains caller-supplied request identities, atomic recording of local effects and the problem of reusing an identity with different parameters. Apply that principle only within the actual provider contract, including its scope and retention period. An internal key does not make an external endpoint idempotent.

• Preserve intent: store the operation identity, provider account, environment and external references, with necessary request parameters in controlled storage and credentials excluded; bind a supported provider idempotency key to this attempt.
• Resolve uncertainty: use the provider's supported status lookup, verified callback or reconciliation evidence. Retry the same attempt only when its documented contract makes that safe.
• Apply the decision: once the defined external evidence is sufficient, ask the wallet to apply its uniquely identified financial operation. Keep provider confirmation and wallet completion separate until the latter is known.
• Escalate deliberately: if the outcome cannot be established, create an owned case with evidence and a next action. Do not manufacture rejection to make routing continue.

Bound retry count and elapsed time, use backoff, and respect provider limits. A circuit breaker can stop further calls to an unhealthy dependency; it cannot decide whether an earlier payment happened. The payment orchestration guide develops routing and reconciliation beyond this adapter boundary.

Receive events durably before applying their effects

A webhook is a provider's notification sent to your endpoint. Receiving it, interpreting it and applying its business effect are separate steps. Define who authenticates it, which account and environment it belongs to, what identifies a duplicate and what a successful acknowledgement promises.

Stripe's webhook guide documents duplicate deliveries, events arriving out of order and signature verification using the unmodified request body. These are examples from Stripe's contract, not a statement that every provider uses the same format or supports every iGaming arrangement. Check each selected provider's authentication, ordering and redelivery rules.

A useful asynchronous design verifies the message and durably records accepted work before acknowledging it under the provider's response contract. A worker then maps and applies it. Recording an event as received must not mark its effect completed: a crash between those steps needs recoverable processing. For local state, atomically commit the effect and the record that this domain operation has completed; if processing also emits a message, durably record that pending message in the same transaction. This is the transactional outbox pattern described by AWS. Delivery can still repeat, so the recipient needs its own safe processing contract.

If the wallet or another owner is remote, a locally stored receipt, or inbox, cannot make the remote effect atomic. Use that owner's idempotent operation identity and retain a retryable completion state. Test two workers processing the same event concurrently; a prior “have we seen it?” query is not sufficient protection. Preserve allowed transitions when late events arrive, and retrieve authoritative state where the contract supports it rather than overwrite a newer decision using arrival time alone.

Record operational references and redacted diagnostics with controlled access. Credentials, payment data and identity documents should not be copied into general logs. Define necessary evidence storage, access and retention separately; keeping every raw payload forever is not an observability strategy.

Replace a provider without abandoning unfinished work

Compatibility means preserving behaviour, not merely parsing JSON. Pin the provider API and event versions actually used, track the adapter mapping version, and test representative payloads with secrets and personal data removed. Include unknown consequential states, newly optional fields, changed units and different error meanings. A contract fixture cannot prove production access, service availability or commercial rights.

Expose capabilities explicitly: supported status lookup, refund or correction operations, currencies, verification checks and the actual wallet mode. Do not silently emulate an unsupported financial operation. A common interface may need to change when a genuinely new domain capability appears; hiding it in an undocumented provider-specific escape hatch moves the coupling rather than removes it.

During replacement, send new eligible work to the approved route while retaining the old provider's references and a resolution path for unfinished payments, rounds or reviews. Keep its callbacks and required evidence access available for the agreed transition. Reconciliation should identify which provider owns each case. Do not replay mutating requests against a new vendor as a migration test.

Read-only shadow comparisons can help only when the actual interfaces, data-sharing permissions and operating arrangement allow them. Decide when the old adapter can be retired from observed completion and agreed retention needs, not just from the date new traffic moved. Production access and exit terms belong in the same plan as code changes.

Test the boundary through failures, not just successful calls

Accept a vertical slice with its failure evidence. A successful request shows that a path works once; it does not show that money or permissions remain correct after interruption. The following are proposed tests for your implementation, not claims that a particular platform has passed them:

• Lost response: the provider acted but the caller timed out. The same intent remains traceable, and recovery does not create another external operation without established safety.
• Duplicate and crash: simultaneous deliveries and a restart after persistence produce one authorised domain effect while allowing unfinished processing to resume.
• Late review: an older identity result is retained as evidence but cannot approve a newer identity version or clear an unrelated account restriction.
• Unsupported outcome: an authentic event with an unmapped consequential state reaches an owned investigation path without an invented financial or eligibility decision.
• Replacement: new work uses the new adapter while an old-provider case can still be investigated and completed through its correct authority.

Monitor transport failures alongside age and count of unresolved attempts, processing backlog, reconciliation discrepancies and time to resolution. Set thresholds from the agreed operating expectations. Alerts need an owner and an action; a healthy HTTP response rate can coexist with a growing queue of unfinished financial work.

Give operations a permitted way to inspect evidence, request a safe retry and escalate a discrepancy. Audit actions and apply the intended role checks to both reads and changes. A support screen should not become an alternative balance writer. Rehearse credential rotation and dependency outages against the selected provider's actual contract.

Commission a boundary the next team can operate

Start with a particular blocked journey or replacement decision. Ask for an implementable boundary package: domain authority, provider contract and capability mapping, outbound request identity, event-processing lifecycle, version strategy, recovery ownership and acceptance evidence. For each decision, record assumptions and the next fact needed to accept it.

The provider-evaluation guide helps confirm that the selected product, access and support arrangements are real. Build one complete integration slice before generalising across providers. Reuse established mechanics, then inspect the next provider's differences instead of declaring integration effort solved by a common interface.

The checklist below is a handover test: can another team explain an uncertain outcome, implement the next adapter and operate unfinished work without reverse-engineering product rules from vendor payloads? A good boundary reduces that dependence. It does not guarantee instant replacement, lower cost or regulatory approval.

Use the custom-versus-turnkey comparison when deciding which integration responsibilities to own or buy. For bet acceptance and settlement authority, read the sportsbook architecture guide. These choices depend on the actual product, contracts and operating team; sharing adapter infrastructure does not make their domain rules interchangeable.

• Authority: which domain may change money, round state or permissions, and what evidence is required?
• Meaning: which provider outcomes map to which internal transitions, and how are unresolved or unsupported states retained?
• Recovery: where are intent, receipts, effects and pending delivery recorded, and what makes retries safe under concurrent processing?
• Change: which versions, capabilities, unfinished cases, access arrangements and retirement evidence are included in provider replacement?