GambleHub-Integrationsleitfaden

1) Überblick und Interaktionsmodell

• API-Anbieter: Sie rufen die GambleHub-API (Wallet, Boni, Berichte) auf.
• Externer Anbieter: Wir rufen Ihre Webhooks/Endpoints (Saldo, Transaktionen, KYC) auf.

1. Edge/API (REST/gRPC, Webhooks)

2. Events (Eventbus: Wetten/Auszahlungen/Wallet/CUS)

3. Reporting (API + S3/SFTP Export)

4. Operationen (Incidents, SLOs, SLAs)

2) Umgebungen, Domains und IP

Der Vertrag SLA ist im Vertrag festgelegt. IP-Updates werden frühzeitig veröffentlicht. Erlauben Sie Allowlist.

3) Authentifizierung und Autorisierung

• OAuth2 Client Credentials: server-to-server ('scope' -s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (issuer = GambleHub): Signatur RS256, Schlüssel im JWKS-Endpunkt.
• mTLS: Gegenseitige TLS-Authentifizierung auf ingress-Ebene (auf Compliance-Anfrage).

POST /oauth2/token grant_type=client_credentials&scope=wallet:write bet:write
→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

Scopes werden bei jedem Anruf überprüft. Für risikoreiche Transaktionen (Auszahlung) wird Step-up verwendet: ein separates Scope und optional eine IP/ASN-Bindung.

4) Versionierung und Kompatibilität

Pfad: '/v1/...', '/v2/...'(Major-Version nicht kompatibel zurück).
Moll und Erweiterung Änderungen - durch die Erweiterung des Schemas (neue optionale Felder).
Deprecations - 90 Tage mit Benachrichtigung.
Die Webhooks werden mit dem Titel 'X-GH-Event-Version: 1' versioniert.

5) Grenzen, Quoten und Idempotenz

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 kehrt mit 'Retry-After' (Sekunden) zurück.
• Alle unsicheren Methoden erfordern einen 'Idempotency-Key' (TTL 24-72 h). Die Wiederholung einer identischen Abfrage gibt das ursprüngliche Ergebnis zurück ('409 IDEMP_REPLAY' bei einem Konflikt).

6) Fehlerstandards

json
{
"type": "https://docs. gamblehub. io/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"trace_id": "a1b2c3...",
"retriable": false,
"errors": [{"field":"amount","code":"min","message":"Must be >= 1"}]
}

Retriable: 5xx/503/504/429 (с `Retry-After`). Non-retriable: 400/401/403/404/409/422/410/415/412.

7) Datenschemata (Kern)

7. 1 Spieler

json
{
"player_id": "p_123",
"country": "CA",
"currency": "CAD",
"rg_flags": {"self_excluded": false, "limits": {"daily_loss": 100}},
"kyc_status": "verified    pending    failed"
}

7. 2 Sitzung

json
{
"session_id": "s_789",
"player_id": "p_123",
"started_at": "2025-11-03T17:55:00Z",
"ip": "203. 0. 113. 5",
"device": {"ua":"...", "os":"Android", "model":"..."}
}

7. 3 Wallet/Transaktionen

json
{
"txn_id": "t_001",
"player_id": "p_123",
"type": "deposit    withdrawal    bet    win    bonus    adjustment",
"amount": "12. 34",
"currency": "EUR",
"balance_after": "123. 45",
"metadata": {"provider":"psp_x","request_id":"r_456"}
}

7. 4 Einsatz/Auszahlung

json
{
"bet_id": "b_456",
"player_id": "p_123",
"game_id": "g_777",
"stake": "1. 50",
"currency": "EUR",
"placed_at": "2025-11-03T17:58:10Z",
"round_id": "rnd_aa1",
"provider": "StudioX"
}

json
{
"settlement_id": "st_456",
"bet_id": "b_456",
"win_amount": "3. 75",
"settled_at": "2025-11-03T17:59:02Z",
"outcome": "win    lose    void"
}

7. 5 Bonus

json
{
"bonus_id": "bo_900",
"player_id": "p_123",
"type": "freespin    cash    wagered",
"state": "issued    active    expired    consumed",
"wagering": {"target": "100. 00","progress":"45. 20","currency":"EUR"}
}

8) REST-API (OpenAPI-Fragmente)

yaml paths:
/v1/wallet/balance/{player_id}:
get:
summary: Get wallet balance security: [{ oauth2: [wallet:read] }]
responses:
'200': { description: OK }
'401': { $ref: '#/components/responses/Problem' }
'404': { $ref: '#/components/responses/Problem' }

/v1/wallet/transactions:
post:
summary: Create wallet transaction security: [{ oauth2: [wallet:write] }]
parameters:
- name: Idempotency-Key in: header required: true schema: { type: string }
responses:
'201': { description: Created }
'409': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }

/v1/bets:
post:
summary: Register bet security: [{ oauth2: [bet:write] }]
responses:
'201': { description: Created }
'422': { $ref: '#/components/responses/Problem' }

9) Webhooks (von GambleHub zu einem Partner)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• „X-GH-Event-Id“: einzigartige UUID
• `X-GH-Signature`: `sha256=`
• „X-GH-Retry“: Versuch Nr
• `X-GH-Event-Version`: `1`

json
{
"event": "bet. settled",
"occurred_at": "2025-11-03T18:00:12Z",
"data": {
"settlement_id": "st_456",
"bet_id": "b_456",
"player_id": "p_123",
"win_amount": "3. 75",
"currency": "EUR",
"outcome": "win"
}
}

Die Antwort des Gastgebers ist, dass nur 2xx als Erfolg gilt. Ansonsten - Retrays: exponentieller Backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; maximal 24 Stunden). Verwenden Sie für die Deduplizierung die' X-GH-Event-Id'.

text expected = base64(hmac_sha256(request_body, SHARED_SECRET))
header  = split(X-GH-Signature, '=')[1]
assert header == expected

10) Reihenfolge des Cashflows (Wallet Flow)

1. deposit (PSP → wallet. credit)

2. bet (hold/authorize или direct debit)

3. settlement (release hold; `win`/`lose`/`void`)

4. withdrawal (wallet. debit → PSP)

Hold-Salden und Multi-Wallets (Real/Bonus) werden unterstützt.

11) Sandbox und Testszenarien

Testspieler:'p _ sbx _', Währungen 'EUR' USD 'CAD'.
Spieleanbieter emulieren: win/lose/void, Rabatteffekte, Verzögerungen.
KYC Sandbox: 'verified' failed 'review' Antworten auf Passvorlagen.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Stavka→vyplata→sverka des Gleichgewichts
• Rollback/void der Runde
• Idempotency bei wiederholtem Einsatz
• Webhook-Absturz mit Retrays und anschließender Deduplizierung
• 429 und korrekt „Retry-After“
• 5xx mit exponentiellem Backoff auf Kundenseite

12) Abstimmungen und Berichterstattung

Reconciliation API

yaml
GET /v1/reports/reconciliation? from=...&to=...&scope=wallet    bets
→ CSV/JSON: { player_id, bet_id, stake, win, currency, balance_delta, provider }

Tägliche Zusammenfassungen: Umsatz, GGR/NGP, Anbieter, Geo/Währungsschnitt.
Export: S3/SFTP mit signierten Manifesten und Dateihashes (SHA256).
Zeitzone der Berichte: UTC (sofern im Vertrag nicht anders angegeben).

13) Beobachtbarkeit und SLO

SLI: Erfolg der API ≥ 99. 95% (28d), p95 Latenz für kritische Methoden, Erfolg der Lieferung von Webhooks.
Burn-alerts (fast/slow) für ein fehlerhaftes Budget.
Trace-Korrelation: 'trace _ id' in Antworten/Protokollen, Drilldown zu Spuren.
Status-Seite: Edge, Wallet, Bets, Webhooks, PSP, KYC Komponenten.

14) Sicherheit und Compliance

PII-Minimierung; PANs/Geheimnisse in Logs/Webhooks sind verboten.
Secret-Management und Schlüsselrotation.
RG (Responsible Gambling): Selbstausschluss-/Limitflags sollten zu einer automatischen Ablehnung von Wetten/Auszahlungen führen.
AML/KYC: Ereignisse' kyc. updated`, `aml. alert 'im Abonnement verfügbar ist; Entscheidungen treffen Sie in Ihrem System oder über unser Modul.
GDPR/DSAR: Endpunkte für das Hochladen/Löschen personenbezogener Daten eines Spielers bei rechtlichen Anfragen.
mTLS und HSTS sind standardmäßig in der Prod-Umgebung aktiviert.

15) Produktivität und Quoten

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Körpergröße: ≤ 256 KB (Spielereignisse), ≤ 64 KB (Geldbörse)

Fordern Sie ein Upgrade des Plans über den Account Manager an, indem Sie die RPS-Prognose/Volumina angeben.

16) Änderungs- und Freigabemanagement

Windows ändern: Geplante Arbeit - nach Zeitplan, Benachrichtigung ≥ 5 Werktage.
Versionsmigrationen: Dual-Write/Dual-Read in der Übergangszeit.
Vertragstests im CI: JSON-Schema, Pflichtfelder, stabiler 'error _ code'.
Canary: Schrittweise Einbeziehung des Verkehrs für neue fitch.

17) Integrationszertifizierung (Checkliste)

• Wett-/Auszahlungsregistrierung/void
• Idempotenz auf allen Write-Endpoints
• Korrekte Handhabung 429/5xx + backoff
• Verifizierung der Webhook-Signatur, Deduplizierung nach 'X-GH-Event-Id'
• Saldenabgleich nach einer Reihe von Ereignissen (win/lose)
• Reconciliation Berichte konvergieren mit Ihren Daten

• Webhook-Retrays implementiert
• Client-Timeouts ≤ 10c, allgemeiner Versuch ≤ 30c
• Kreisbruch auf Abhängigkeiten

• Geheimnisse im Secret Manager speichern
• PII-Revision in Protokollen
• RG/AML-Flags werden in Echtzeit berücksichtigt

18) Häufig verwendete Szenarien

18. 1 Wettregistrierung mit Idempotenz

POST /v1/bets
Idempotency-Key: bet-p_123-rnd_aa1-1

{ "player_id":"p_123","game_id":"g_777","stake":"1. 50","currency":"EUR","round_id":"rnd_aa1" }
→ 201 Created { "bet_id":"b_456" }

18. 2 Feil Webhook mit anschließendem Erfolg

1. Ihr Server ist → 5xx → Backoff-Retrays nicht erreichbar.
2. Nach der Wiederherstellung - nehmen Sie die gleiche' X-GH-Event-ID '→ sind verpflichtet, die Duplikate zu ignorieren.

18. 3 Teilweise Verschlechterung des Anbieters

Wir werden 503 zurückgeben; Wiederholen Sie mit Backoff.
Bei langer Degradation - Stopp-Markierung des Anbieters und inkl. Smart-Routing (wenn im Vertrag).

19) DevEx und Support

Portal: Schlüssel, Verwendung, Webhooks, Lieferprotokolle, SLO-Dashboards, Export von Berichten.
Webhooks replay: Neulieferung nach Datumsbereich/ID.
Vorfälle: Auto-Ticket-Erstellung, Kriegsraum, Postmortem ≤ 48 Stunden SEV-1.
Kommunikation: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) Onboarding-Plan (2-4 Wochen)

1. Woche 1: Schlüsselübergabe, Sandbox-Verbindung, Basisszenarien (Wette/Auszahlung/Wallet).
2. Woche 2: Webhooks und Abstimmungen, RG/KYC Flags, Belastungstests, 429/5xx Verhalten.
3. Woche 3: Berichterstattung (Reconciliation, Uploads), Sicherheit (Signaturen, Geheimnisse), Vertragstests.
4. Woche 4: Zertifizierung, kanarische Aufnahme in die Produktion, Überwachung, Kontaktmatrix.

21) Mini-FAQ

Ist gRPC möglich?
Ja, auf Anfrage; Das Mapping von HTTP-Fehlercodes wird in der Spezifikation bereitgestellt.

Wie bekomme ich Retro-Daten?
Durch 'reconciliation' Berichte ('von/zu' Daten) oder S3/SFTP upload.

Wie erhöhe ich meine Limits?
Über das Portal/Account Manager mit Angabe der prognostizierten RPS/Wettbewerbsfähigkeit.

Was ist die Quelle der Wahrheit des Gleichgewichts?
Transaktionslog der GambleHub Wallet + täglicher Abgleich (Reconciliation).

Summe

Die Integration mit GambleHub basiert auf einem klaren Vertrag: stabile APIs und Schemata, signierte Webhooks, Idempotenz und Retrays, transparente Limits und Reporting sowie Sicherheits- und Compliance-Anforderungen. Wenn Sie diesem Leitfaden und den Zertifizierungsschecklisten folgen, werden Sie schnell in den Prod einsteigen und zuverlässige Cashflows und konsistente Berichte ohne Diskrepanzen sicherstellen.