Adapter integration spec

This document is the public contract for integrating a casino platform with casinocrm.io. Whatever platform you're wiring up, follow this spec end to end.

Table of contents

1. Contract overview
2. Canonical events
3. Bonus flow
4. KYC flow
5. Security (HMAC + replay)

At a glance

casinocrm.io connects to your casino platform via two flows:

        ┌─────────────┐                        ┌─────────────┐
        │   PLATFORM  │  ── webhook events ──→ │    casinocrm.io     │
        │             │  ←─ adapter calls ─── │             │
        └─────────────┘                        └─────────────┘

Inbound to casinocrm.io (you implement webhook senders):

• POST https://ingest.casinocrm.io/v1/events — every player action (signup, deposit, bet, KYC change, RG change). Bearer API key auth. Keyed by anonymous_id (your stable player id). See Events ingestion.
• /v1/adapters/<slug>/webhooks/bonus-events — bonus lifecycle from your platform. HMAC-signed.
• /v1/adapters/<slug>/webhooks/kyc-events — KYC lifecycle from your platform. HMAC-signed.

Outbound from casinocrm.io (you expose adapter endpoints):

• POST <your-base>/v1/bonuses/grant — issue a bonus on a player's wallet.
• POST <your-base>/v1/bonuses/cancel — cancel an active bonus.
• GET <your-base>/v1/bonuses/{id} — current bonus status (for reconciliation).
• (KYC + RG outbound calls — when tenant.kyc_model in {crm_owns, dual} or RG features enabled)

The adapter contract is bidirectional but loosely coupled — a platform that doesn't support outbound bonus issuance can integrate event-only (we just track events; bonuses are managed entirely on the platform UI).

What you need before starting

Item	How to get it
API key	casinocrm.io admin: Settings → API keys → Create. Format: ucrm_pk_<env>_<id>_<secret>
Adapter slug	Coordinated with casinocrm.io team. Lowercase, hyphenated. Example: acme-prod.
HMAC shared secret	One per environment, exchanged out-of-band. casinocrm.io stores under casinocrm.io_ADAPTER_<SLUG>_WEBHOOK_SECRET env var.
Webhook URL	Your inbound URL where casinocrm.io POSTs adapter callbacks (cancel-bonus etc.).
Test tenant	casinocrm.io provisions a sandbox tenant with seeded test players.

Capability declaration

Your adapter declares static capabilities at registration:

{
  "slug": "acme-prod",
  "displayName": "Acme Platform",
  "capabilities": {
    "verticals": ["casino", "sportsbook"],
    "bonus": { "issue": true, "cancel": true, "query_status": true },
    "kyc":   { "initiate": false, "query": true, "update": false, "webhooks": true },
    "rg_features": ["self_exclusion", "deposit_limit_daily", "loss_limit_daily", "session_limit_minutes"],
    "wallet": { "balance_pull": true, "balance_push": false },
    "signature_scheme": "hmac_sha256"
  }
}

The effective capabilities for a tenant = tenant.config ∩ adapter.capabilities. If a feature isn't supported on either side, casinocrm.io either:

• Hard-blocks when the gap is critical (verticals mismatch, KYC model mismatch on crm_owns)
• Falls back to CRM-only enforcement when the gap is recoverable (RG features → capability_mock pattern)

Versioning

This spec is versioned in lockstep with the casinocrm.io apps/api schema. Breaking changes require a major version bump + deprecation notice. Current version: v1.

The spec doc on docs.casinocrm.io is always authoritative. The PDF / Markdown export reflects a snapshot.

Support channels

• Slack — operator-only channel; ask the casinocrm.io team for an invite
• Email — integrations@casinocrm.io (bug reports, feature requests, integration questions)