How to connect providers via API: handshake, certification, sandbox

Full article

💡 18+. The material is engineering and applied, not a call to play. By "provider" we mean RGS/live studio/jackpot/service; under the "platform" - PAM/wallet/cash desk/bonuses/RG.

1) Integration map: from application to production

Stages:

1. Presale and Due Diligence: legal checks, geo/licenses, content compatibility and RG policies.

2. Handshake and security: issuing sandbox accesses, key exchange (mTLS/HMAC), registration with Schema Registry.

3. Technical design: we confirm the domain model (sessions/bets/settlements/events), idempotency, error codes.

4. Sandbox integration: wallet/PSP/RG emulators, test players, rain and take scenarios.

5. Certification: mandatory test run, protocol signing, loads and chaos cases.

6. Staging/UAT: combat configs without real money, canary traffic.

7. Go-Live: key company, enabling feature flags, SLO monitoring, post-incident readiness.

2) Handshake: authentication, authorization, tracing

2. 1 Sharing secrets and scopes

mTLS (per brand/region certificates) and/or Client Credentials OAuth2.

HMAC/EdDSA request body signature (adds non-repudiation).

Скоупы: `sessions:write`, `bets:write`, `settlements:write`, `events:publish`.

2. 2 Mandatory headings

'X-Trace-Id '- end-to-end tracing.

`X-Brand-Id`, `X-Region`, `X-Provider-Id`.

'X-Idempotency-Key '- for all write operations.

2. 3 Health-check (before code)


GET /health
→ 200 {"status":"ok","version":"1. 7. 2","time":"2025-10-23T10:00:00Z"}

3) Sandbox: what is there and how to use it

Environment composition:

Wallet emulator ('/wallet/debit	credit	rollback ') with idempotency and delays.
RG hooks ('/rg/check ',' rg. limit. hit ') and test profiles (self-exclusion/limits).
False aggregator/jackpot for contributions/triggers.
Fake KYC/AML responses (allow/deny/pending).
Event bus (Kafka/Pulsar) with test topics and Schema Registry.

Harmony with reality:

Similar versions of schemes and rate limits as in the sale.
Time-sky, delivery doubles, out-of-order - built-in emulation buttons.

Set of test players/currencies:


p_demo_1 (EUR), p_demo_2 (USD), p_blocked_rg (denied), p_low_balance

4) Resource model and minimum contract

4. 1 Session creation


POST /v1/sessions
{
"player_id":"p_demo_1",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE"
}
→ 201 {"session_id":"s_456","expires_at":"2025-10-23T19:10:00Z"}

4. 2 Rate authorization (hold)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 {"status":"authorized","hold_id":"h_zz1"}

4. 3 Settlement (round outcome)


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status":"credited","settlement_id":"st_77"}

4. 4 Errors (single diagram)


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

5) Events and schemes: without this you will not pass certification

Basic topics:

`session. started	ended`, `bet. authorized	settled	rolled_back`, `bonus. issued	consumed`, `wager. progress. updated`, `wallet. debit.`, `wallet. credit.`, `rg. limit. hit`, `rg. reality_check`.

Example Avro/JSON Schema (fragment'bet. settled`):

json
{
"event_type":"bet. settled",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_demo_1",  "trace_id":"tr_a1b2",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1"
}

Rules: backward-compatible evolution, test for "duplicates and late events," participation by 'tenant _ id/player _ id'.

6) Integration certification: what exactly is being checked

6. 1 Functional scenarios (minimum)

Retry the'authorize/settle 'request with the same'X-Idempotency-Key' → the same response.

Out-of-order: 'settle' came without 'authorize' → correct failure.

Rollback chains when the wallet/network falls.

RG stops: self-exclusion/loss limit/time → prohibit bet.

Bonus/vager: contribution by game type, max bet, deadlines.

6. 2 Load

p95 'bet/settle' in budgets (e.g. '<200-300 ms'), no "storms" of retrays.

Event streams reach BI ≤ 5 min.

6. 3 Chaos cases

Delivery doubles, outbox/CDC delays, region "dump," partial settlement.

6. 4 Deliverables

Test protocol with timecodes/trace-id.

SLO report (latency/error/lag).

Security summary (keys, rotations, accesses, Vault/HSM).

7) Version and migrations

HTTP: '/v1/... 'in transit, events:' schema _ version 'in body.

SemVer: minor - adding optional fields; major - only through the new prefix '/v2/'.

Deprecation headers: 'Deprecation', 'Sunset', dashboard use mirror.

Feature flags: the "double letter" of events ('v1' and 'v2') in transition.

8) Safety and compliance

mTLS + S2S signatures, short-lived tokens, bounded scopes.

Zero-trust: network policies, per-brand/region keys.

Data residency & PII: storage and logs in the region; RLS/masking.

WORM audit: changes to limits, RTP profiles, jackpot configs.

RG/AML: synchronous stop lights on bet/pay; SAR/STR reporting.

9) Exit to production: launch checklist

Before traffic is enabled

Rotation of sandbox secrets → prod keys.

Included dashboards p95/p99, error-rate, queue-lag, settle-lag.

Alert SLO: breach by latency/error/lag, surge 'DUPLICATE/IDEMPOTENCY _ MISMATCH'.

DR-plan: RPO ≤ 5 min, RTO ≤ 30 min; "red button" - stop new sessions.

Canary

1-5% audience/games/geo; automatic rollback in case of SLO violation.

Post-monitoring 24-72 hours, ledger/report reconciliation.

10) Anti-patterns (red flags)

Publishing events bypassing outbox/CDC.

Absence of'X-Idempotency-Key 'on write operations.

Manual edits of balances/settlements in the database.

Single keys for multiple brands/regions.

BI and regulatory reports on top of the OLTP combat database.

Zero degradation: the fall of the provider brings down the wallet/platform.

11) Checklists

For the provider

I always send 'X-Trace-Id' and 'X-Idempotency-Key'.
I support repeating with the same key without side effects.
Publish schema events from Registry; store'schema _ version '.
Backoff retrains and deduplication are implemented.
RG stops and bonus limits are enforced in real-time.
Access and secrets - per brand/region, rotation configured.

For platform

Outbox/CDC on all money paths; end-to-end tracing.
SLO dashboards: p95/99, error-rate, queue-lag, settle-lag.
Deprecation/Sunset process, a double letter of events on migrations.
DR/xaoc exercises, incident management and post-mortems.
Degradation modes: 'no new sessions', disable promo/jackpot.

12) Example of a "minimal" integration playbook (TL; DR)

1. Sign an NDA/contract → issue sandbox accesses and schemes.

2. Exchange mTLS/HMAC certificates; start'provider _ id '.

3. Agree on minimum endpoints: 'sessions', 'bets/authorize', 'bets/settle', 'rollback'.

4. Connect to the Sandbox bus and Registry; drive out functional/chaos cases.

5. Pass the certification protocol: logs, trace-id, SLO report.

6. Switch keys to food, turn on the canary, observe SLO.

7. Record post-release metrics and "lessons" in changelog.

Successful connection of the provider is not only an API, but a controlled process: a secure handshake, a realistic sandbox, strict certification, observability and clear compatibility rules. By following the described invariants (idempotency, outbox/CDC, RG/AML stops, SLO and DR), you accelerate integrations, avoid monetary incidents and get predictable releases - without surprises for players, regulators and businesses.