Adapter integration spec

This document is the public contract for integrating a casino platform with UCRM. 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

UCRM connects to your casino platform via two flows:

        ┌─────────────┐                        ┌─────────────┐
        │   PLATFORM  │  ── webhook events ──→ │    UCRM     │
        │             │  ←─ adapter calls ─── │             │
        └─────────────┘                        └─────────────┘

Inbound to UCRM (you implement webhook senders):

• /v1/events — every player action (signup, deposit, bet, KYC change, RG change). Bearer API key auth.
• /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 UCRM (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	UCRM admin: Settings → API keys → Create. Format: ucrm_pk_<env>_<id>_<secret>
Adapter slug	Coordinated with UCRM team. Lowercase, hyphenated. Example: acme-prod.
HMAC shared secret	One per environment, exchanged out-of-band. UCRM stores under UCRM_ADAPTER_<SLUG>_WEBHOOK_SECRET env var.
Webhook URL	Your inbound URL where UCRM POSTs adapter callbacks (cancel-bonus etc.).
Test tenant	UCRM 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, UCRM 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 UCRM 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 UCRM team for invite
• GitHub Issues — bug reports + feature requests
• Email — integrations@casinocrm.io