Guide d'intégration GambleHub

1) Aperçu et modèle d'interaction

• Fournisseur d'API : vous appelez l'API GambleHub (portefeuille, bonus, rapports).
• Fournisseur externe : Nous appelons vos webhooks/endpoints (bilan, transactions, KYC).

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

2. Événements (event bus : paris/paiements/portefeuille/CUS)

3. Reporting (API + exportation S3/SFTP)

4. Opérations (incidents, SLO, crédits SLA)

2) Environnements, domaines et IP

Le SLA contractuel est fixé dans le contrat. Les mises à jour de la PI sont publiées à l'avance. Autorisez Allowlist.

3) Authentification et autorisation

• OAuth2 Client Credentials : serveur-à-serveur ('scope' -' wallet : read ',' wallet : write ',' bet : write ',' report : read ').
• JWT (issuer = GambleHub) : signature de l' RS256, clés dans l'endpoint JWKS.
• mTLS : authentification réciproque TLS au niveau de l'ingress (à la demande de la conformité).

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

Les scopes sont vérifiés à chaque appel. Pour les opérations à haut risque (paiement), step-up est utilisé : un scope séparé et, en option, une liaison IP/ASN.

4) Versioning et compatibilité

Chemin : '/v1/... ', '/v2/...' (version majeure incompatible avec l'arrière).
Changements mineurs et extensifs - par l'extension du schéma (nouveaux champs optionnels).
Dépressions - 90 jours avec préavis.
Les webhooks sont versionnés avec la rubrique « X-GH-Event-Version : 1 ».

5) Limites, quotas et idempotence

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• Le 429 revient avec « Retry-After » (secondes).
• Toutes les méthodes dangereuses nécessitent 'Idempotency-Key' (TTL 24-72 h). La répétition d'une requête identique renvoie le résultat d'origine ('409 IDEMP_REPLAY' en cas de conflit).

6) Normes d'erreur

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) Schémas de données (noyau)

7. 1 Joueur

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 Session

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 Portefeuille/transactions

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 Taux/paiement

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) API REST (fragments OpenAPI)

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 (de GambleHub à un partenaire)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Event-Id ': un UUID unique
• `X-GH-Signature`: `sha256=`
• « X-GH-Retry » : tentative n °
• `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"
}
}

Réponse de l'hôte - seulement 2xx est considéré comme un succès. Autrement, les retraits : backoff exponentiel (1s, 3s, 10s, 30s, 2m, 10m, 30m ; 24 heures maximum). Pour la déduplication, utilisez "X-GH-Event-Id'.

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

10) Ordre des flux de trésorerie (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)

Les balances hold et les portefeuilles multiples (réels/bonus) sont pris en charge.

11) Sandbox et scénarios de test

Joueurs de test : 'p _ sbx _', devises 'EUR' USD'CAD '.
Les fournisseurs de jeux émulent : win/lose/void, discounts, retards.
KYC sandbox : réponses 'verified'failed 'review' par modèles de passeport.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Stavka→vyplata→sverka l'équilibre
• Retour/void round
• Idempotency à nouveau parié
• Échec du webhook avec retraits et déduplication subséquente
• 429 et correct 'Retry-After'
• 5xx avec un backoff exponentiel côté client

12) Rapprochement et établissement de rapports

Reconciliation API

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

Résumés quotidiens : chiffres d'affaires, GGR/NGP, fournisseurs, coupe géo/devises.
Exportation : S3/SFTP avec des manifestes signés et des hachages de fichiers (SHA256).
Temps de déclaration : UTC (sauf accord contraire dans le contrat).

13) Observabilité et SLO

SLI : succès de l'API ≥ 99. 95 % (28d), p95 latitude pour les méthodes critiques, succès de la livraison de webhooks.
Burn-alerts (fast/slow) sur un budget erroné.
Trace-corrélation : 'trace _ id'dans les réponses/logs, drilldown to tracks.
Page d'état : Edge, Wallet, Bets, Webhooks, PSP, KYC.

14) Sécurité et conformité

La minimisation des PII ; Les PAN/secrets dans les logs/webhooks sont interdits.
Gestion secrète et rotation des clés.
RG (Responsible Gambling) : les drapeaux d'auto-exclusion/limites doivent entraîner un refus automatique des taux/paiements.
AML/KYC : événements 'kyc. updated`, `aml. alert 'sont disponibles par abonnement ; les décisions sont prises dans leur système ou via notre module.
GDPR/DSAR : endpoints pour décharger/supprimer les données personnelles du joueur sur demande légale.
mTLS et HSTS sont activés par défaut dans l'environnement pro.

15) Productivité et quotas

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Taille du corps : ≤ 256 Ko (jeux), ≤ 64 Ko (portefeuille)

Demandez une mise à niveau du plan via le compte gestionnaire en indiquant les prévisions RPS/volumes.

16) Gérer les changements et les mises à jour

Changement de Windows : travaux planifiés - programmés, notification ≥ 5 jours ouvrables.
Migrations de version : dual-write/dual-read pendant la période de transition.
Tests de contrat dans CI : schéma JSON, champs obligatoires, stable 'error _ code'.
Canary : intégration progressive du trafic pour les nouvelles fiches.

17) Certification d'intégration (Check-list)

• Inscription de taux/paiement/void
• Idempotence sur tous les write-endpoints
• Traitement correct 429/5xx + backoff
• Vérification de la signature des webhooks, déduplication par 'X-GH-Event-Id'
• Rapprochement du bilan après une série d'événements (win/lose)
• Les rapports de reconnaissance convergent avec vos données

• Retraits de webhooks mis en œuvre
• Délai d'attente des clients ≤ 10c, tentative générale ≤ 30c
• Circuit-breaker sur les dépendances

• Garder des secrets dans un gestionnaire de secrets
• Édition PII dans les loges
• Les drapeaux RG/AML sont comptés en temps réel

18) Scénarios fréquemment utilisés

18. 1 Inscription de taux avec idempotence

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 suivi d'un succès

1. Votre serveur n'est pas disponible → 5xx → backoff.
2. Après la restauration - prenez le même 'X-GH-Event-Id' → sont tenus d'ignorer les doublons.

18. 3 Dégradation partielle du fournisseur

Nous vous rendrons 503 ; répétez avec backoff.
En cas de dégradation prolongée, le marquage stop du fournisseur et le routage intelligent (si dans le contrat).

19) DevEx et support

Portal : clés, utilisation, webhooks, logs de livraison, SLO dashboards, exportation de rapports.
Webhooks replay : livraison répétée selon la plage de dates/ID.
Incidents : auto-création de ticket, war-room, post mortem ≤ 48h par SEV-1.
Communications : # partners-status canal/mail on-call 24 × 7 (Enterprise).

20) Plan Onboard (2-4 semaines)

1. Semaine 1 : délivrance de clés, connexion sandbox, scénarios de base (pari/paiement/portefeuille).
2. Semaine 2 : webhooks et rapprochements, drapeaux RG/KYC, tests de charge, comportement 429/5xx.
3. Semaine 3 : reporting (reconciliation, déchargement), sécurité (signatures, secrets), tests contractuels.
4. Semaine 4 : certification, canary-inclusion dans la vente, surveillance, matrice de contact.

21) Mini-FAQ

Puis-je avoir gRPC ?
Oui, sur demande ; le mappage des codes d'erreur sur HTTP est fourni dans la spécification.

Comment obtenir des données rétro ?
Via les rapports « reconciliation » (dates « from/to ») ou le S3/SFTP de déchargement.

Comment augmenter les limites ?
Par l'intermédiaire d'un portail/gestionnaire de compte indiquant les RPS/concurrentiels prévisionnels.

Que considérer comme la source de la vérité de l'équilibre ?
Journal transactionnel du portefeuille GambleHub + rapprochement quotidien (reconciliation).

Résultat

L'intégration avec GambleHub repose sur un contrat clair : API et schémas stables, webhooks signés, idempotence et retraits, limites transparentes et rapports, exigences de sécurité et de conformité. En suivant ce guide et les checklists de certification, vous passerez rapidement à la trappe en vous assurant que les flux de trésorerie sont fiables et que les rapports sont cohérents sans divergence.