Testing your integration

Start after your account contact has confirmed organization access, deployment, provider availability, callback configuration and funding or any agreed welcome credits. Use the issued credential unchanged. Real-session validation involves real callbacks and can move money; demo previews do not validate wallet settlement.

See Environments & testing for the prerequisites.

Tip

Use authorized test players and track every wallet movement. Verify signatures, process transactions durably and replay stored results for duplicates. A demo or an advisory check is not go-live approval.

The recommended test sequence

Run these in order during integration. Each step exercises a distinct money-path failure mode that is much cheaper to find here than in production.

1. Catalog + session round-trip

• GET /v1/games → confirm you receive a populated list.
• POST /v1/sessions with a low-volatility game and a small balance (e.g. EUR 1.00 minor units = 100).
• Verify the response shape matches your client’s expectations — session_id, game_url, provider_code.
• Redirect a browser to game_url immediately — it is single-use.
• If you use TRUE LABS’ URL-navigation fallback in a sandboxed iframe, launch with insufficient balance and click its Top-up CTA. Confirm that the top-level page reaches the exact deposit destination without a browser SecurityError — the explicit deposit_url when you provide one, or the return_url fallback when you omit it — and that this route opens the cashier. When the destination differs from the current page by origin, path, or query, this path performs a full document navigation and may recreate the game iframe.
• If your front-end implements a fragment hook for TRUE LABS, or both sides implement an agreed event bridge, create a new session with a fresh Idempotency-Key, run the same scenario, and confirm that the existing cashier opens with no top-level Document request. For a fragment hook, confirm that the deposit URL differs from the current top-level URL only by the fragment, the fragment is removed without reload, the existing game iframe node/session is preserved while opening the cashier, and repeated clicks after closing the cashier without a deposit work. Cover supported browsers and canonical routes with any locale or query parameters. For an event bridge, reject messages whose schema, source iframe, or origin does not match the integration contract. Verify the post-deposit balance and game-relaunch policy separately.

2. Callback signature verification — both happy path and tampered

• Trigger a real spin in the launched game. The provider emits a bet callback that arrives at your callback_url with an X-SIGNATURE header.
• Confirm your signature verification accepts legitimate signatures. Return success only after the callback has passed validation and its wallet outcome and replayable response are durably stored.
• Tamper-test your verifier. Take a captured legitimate callback, change one byte in the body, replay it to your endpoint. Reject it with 4xx (the signature examples use 401) and no wallet movement. A 5xx or handler crash does not pass this test.
• Replay-test. Capture a legitimate callback and re-send it. Your own dedup by integration/organization, provider_code and transaction_id (wallet contract) must short-circuit the replay without any wallet movement. The platform does not enforce a signature-timestamp replay window — your dedup IS the defence.

3. Idempotency

• POST the same Idempotency-Key twice to /v1/sessions with the same body. Confirm the second response is identical to the first and that you see X-Idempotent-Replayed: true in headers.
• Keep that session key bound to its original body: the session path can replay the cached response without comparing a changed body. Do not expect a body-conflict 409 on /v1/sessions.
• For authorized free-round issuance tests, verify that the same key and body replay the recorded grant result, while a different body returns 409 idempotency_conflict. Do not expect the session replay header or session cache TTL on this endpoint.
• Test session cache expiry in a controlled fixture. Its completed-response cache lasts 24 hours from storage; repeating a request after expiry can create a new session. Reconcile an ambiguous outcome before another real operation. See the endpoint-specific idempotency contract.

4. Wallet reconciliation

• After ~50 spins, fetch GET /v1/transactions and reconcile against your internal wallet ledger.
• Reconcile paid bet debits, free bets without real-money debit, wins (including supported zero-win settlements), and refunds of original recorded debits according to the wallet contract. Provider-specific legs may be settled internally; do not infer a missing callback from an API row alone.
• Drift in this stage means your callback handler has a race condition, a missed transaction, or a duplicated one. Fix it now.

5. Failure-mode coverage

Force each of these and confirm your handler does the right thing:

Scenario	How to force	What should happen
Slow callback response	Add sleep(15) to your callback handler temporarily	Observe the documented delivery outcome and retry eligibility; reconcile whether the wallet committed before requesting recovery
5xx callback response	Return 500 from your handler for one spin	Verify behavior against the deployed retry policy, including exhausted-delivery handling
Insufficient balance	Set wallet to less than the next bet amount	Provider receives the rejection, player sees an error
Self-excluded player	Mark the player self-excluded in your system before launching	POST /v1/sessions returns 403 with E3004 player_self_excluded
Reused session URL	Open game_url a second time after the player has already launched	Player sees provider error page; no wallet movement

6. Readiness check (callback checklist)

Where your deployment provides the cabinet Run check control, it runs an advisory suite against the configured callback URL. Confirm availability and parameters in your deployment. Its results do not grant access or go-live approval.

What arrives at your endpoint is a real callback. Same body shape, same X-SIGNATURE, same Content-Type as production traffic; the only marker is an extra X-Aggregator-Readiness: probe header. If your wallet processes it, it moves money on the player it names — so point the check at a test account.

By default the probe generates its own UUIDs for player_id, session_id, and game_id. A wallet that only answers for players it already knows cannot return a balance for an invented one, so under Run parameters you can set:

Parameter	Default	Use it when
Test player ID	generated UUID	your wallet requires a player that exists
Currency	EUR	you settle in a different currency
Bet amount	1.00 (major units, sent as minor)	your limits reject 1.00

What each scenario expects:

• Accepted callbacks (bet, win, refund, free-round legs) — 2xx with a JSON body carrying balance and currency, and Content-Type: application/json.
• Duplicates — the same integration/organization, provider_code and transaction_id replayed with an identical body must return the stored original status and body, with no second wallet movement.
• Rejections (invalid paid-bet amount, negative amount, unsupported currency, conflicting replay, bad or missing signature, non-JSON content type) — a 4xx. Distinguish invalid zero-value paid bets from supported free-round zero-win settlements. A 5xx does not count as successful input rejection: a handler crash must not pass validation, and retry eligibility depends on the deployed path.
• Reachability — proven by any HTTP response. A redirect fails it: callback POSTs are not followed.

Scenarios are a chain, not a flat list. A duplicate can only be judged against a debit the wallet accepted, and a refund returns a bet that must exist first. When the debit scenario fails, the ones that depend on it are reported as skipped with the prerequisite named, not as failures of their own.

7. Going-live readiness

Once steps 1-5 are green, walk through the Go-live checklist before opening customer traffic.

Tools

• Postman collection — generated from the OpenAPI spec. Import the YAML into Postman to get every endpoint pre-configured.
• Demo sessions for game previews without wallet involvement: POST /v1/demo-sessions.
• Echo callback receiver (coming soon) — a platform-hosted callback URL that signs back to your operator account, so you can test signature verification before standing up your own callback endpoint.

What used to be here

When following an older guide, confirm the credential and deployment policy applicable to your integration. Do not rewrite a stored key or its prefix or assume historical credentials remain accepted. The unified-key format applies only after that rollout is enabled.