GambleHub Integration Guide

1) Overview and interaction model

• API provider: you call the GambleHub API (wallet, bonuses, reports).
• External provider: we call your webhooks/endpoints (balance, transactions, KYC).

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

2. Events (event bus: bets/payouts/wallet/ICC)

3. Reporting (API + S3/SFTP export)

4. Operations (incidents, SLO, SLA credits)

2) Environments, domains and IP

The contractual SLA is fixed in the contract. IP updates are published in advance. Allow Allowlist.

3) Authentication and authorization

• OAuth2 Client Credentials: server-to-server ('scope' s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (issuer = GambleHub): RS256 signature, keys in the JWKS endpoint.
• mTLS: mutual TLS authentication at the ingress level (at the request of compliance).

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

Scopes are checked on each call. For high-risk operations (payments), step-up is used: a separate scope and, optionally, binding to IP/ASN.

4) Versioning and compatibility

Path: '/v1/... ', '/v2/...' (major version is incompatible back).
Minor and expanding changes - through the expansion of the scheme (new optional fields).
Decrements - 90 days with notice.
Webhooks are versioned with the title 'X-GH-Event-Version: 1'.

5) Limits, quotas and idempotency

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 returns with 'Retry-After' (seconds).
• All unsafe methods require'Idempotency-Key '(TTL 24-72 h). Repeating an identical query returns the original result ('409 IDEMP_REPLAY' on conflict).

6) Error standards

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) Data schemas (core)

7. 1 Player

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 Wallet/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 Rate/payout

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 fragments)

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 (GambleHub to Partner)

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

Host response - only 2xx is considered a success. Otherwise - retrai: exponential backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; maximum 24 hours). Use'X-GH-Event-Id 'for deduplication.

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

10) Cash flow order (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 balances and multi-wallets (real/bonus) are supported.

11) Sandbox and test scenarios

Test players: 'p _ sbx _', currencies' EUR'USD' CAD '.
Game providers emulate: win/lose/void, discounts, delays.
KYC sandbox: 'verified' failed 'review' responses on passport templates.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Balance Sheet Stavka→vyplata→sverka
• Pullback/void round
• Idempotency at re-bid
• Failure of webhook with retrays and subsequent deduplication
• 429 and correct 'Retry-After'
• 5xx with client-side exponential backoff

12) Reconciliations and Reporting

Reconciliation API

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

Daily summaries: turnovers, GGR/NGP, providers, geo/currency breakdown.
Export: S3/SFTP with signed manifests and file hashes (SHA256).
Reporting time zone: UTC (unless otherwise specified in the contract).

13) Observability and SLO

SLI: success of API ≥ 99. 95% (28d), p95 latency for critical methods, webhook delivery success.
Burn-alerts (fast/slow) on an erroneous budget.
Trace correlation: 'trace _ id' in responses/logs, drilldown to traces.
Status page: Edge, Wallet, Bets, Webhooks, PSP, KYC components.

14) Safety and compliance

PII minimization; PAN/secrets are prohibited in logs/webhooks.
Secret-management and key rotation.
RG (Responsible Gambling): self-exclusion/limit flags should result in automatic denial of bets/payments.
AML/KYC: 'kyc' events. updated`, `aml. alert 'are available by subscription; make decisions in your system or through our module.
GDPR/DSAR: endpoints for uploading/deleting player's personal data for legal requests.
mTLS and HSTS are enabled by default in the production environment.

15) Performance and quotas

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Body size: ≤ 256 KB (gaming events), ≤ 64 KB (wallet)

Request an upgrade of the plan through the account manager, specifying the RPS forecast/volumes.

16) Change and Release Management

Change windows: scheduled work - on schedule, notification ≥ 5 working days.
Version migrations: dual-write/dual-read during the transition period.
CI contract tests: JSON schema, required fields, stable'error _ code '.
Canary: gradual inclusion of traffic for new features.

17) Integration certification (Check-list)

• Bid/Pay Registration/void
• Idempotency on all write-endpoints
• Correct 429/5xx + backoff processing
• Webhook Signature Verification, X-GH-Event-Id Deduplication
• Balance reconciliation after series of events (win/lose)
• Reconciliation reports agree with your data

• Webhook retreats are implemented
• Client timeouts ≤ 10c, total attempt ≤ 30c
• Circuit-breaker on dependencies

• Storing Secrets in the Secret Manager
• PII Edition in Logs
• RG/AML flags are considered in real time

18) Frequently used scenarios

18. 1 Rate registration with idempotency

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 Fail webhook followed by success

1. Your server is unavailable → 5xx → backoff retro.
2. After recovery - take the same 'X-GH-Event-Id' → are obliged to ignore duplicates.

18. 3 Partial degradation of the provider

We will refund 503; repeat with backoff.
With long degradation - stop marking of the provider and incl. smart-routing (if in the contract).

19) DevEx and support

Portal: keys, usage, webhooks, delivery logs, SLO dashboards, export reports.
Webhooks replay: redelivery by date range/ID.
Incidents: auto-creation of a ticket, war-room, postmortem ≤ 48 hours on SEV-1.
Communications: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) Onboarding plan (2-4 weeks)

1. Week 1: key issuance, sandbox connection, base scenarios (bet/pay/purse).
2. Week 2: Webhooks and Reconciliations, RG/KYC Flags, Load Tests, 429/5xx Behavior.
3. Week 3: reporting (reconciliation, uploads), security (signatures, secrets), contract tests.
4. Week 4: certification, canary-inclusion in sales, monitoring, contact matrix.

21) Mini-FAQ

Can I have gRPC?
Yes, on request; HTTP error code mapping is provided in the specification.

How to get retro data?
Via 'reconciliation' reports (from/to dates) or upload S3/SFTP.

How do I lift my limits?
Through the portal/account manager indicating forecast RPS/competitiveness.

What is considered the source of the truth of the balance?
GambleHub wallet transaction log + daily reconciliation.

Total

Integration with GambleHub is built on a clear contract: stable APIs and schemes, signed webhooks, idempotency and retrays, transparent limits and reporting, as well as security and compliance requirements. By following this guide and certification checklists, you will quickly reach the market, providing reliable cash flows and consistent reports without discrepancies.