Skip to main content

KYC flow

KYC has four ownership models — pick once per tenant; the model dictates which sides the contract supports.

Model: platform_owns​

Most common for casinos. The platform handles all of KYC; CRM mirrors state via webhooks.

You implement: webhook senders for the lifecycle below.

You DON'T implement: outbound KYC endpoints (CRM never calls you for KYC).

Webhook events​

POST /v1/adapters/<slug>/webhooks/kyc-events

// kyc.submitted
{
  "event": "kyc.submitted",
  "event_id": "evt-uuid",
  "ts": "2026-05-08T...",
  "player_external_id": "casino_player_001",
  "level": 1,
  "data": { "documents": ["passport", "selfie"] }
}

// kyc.approved
{
  "event": "kyc.approved",
  "level": 2,
  "data": { "expires_at": "2027-05-08T..." }   // optional TTL
}

// kyc.rejected
{
  "event": "kyc.rejected",
  "level": 1,
  "data": { "reason": "document_expired" }
}

// kyc.expired
{ "event": "kyc.expired", "level": 2, "data": {} }

// kyc.level_upgraded — player started higher-level submission
{ "event": "kyc.level_upgraded", "level": 3, "data": {} }

State transitions enforced server-side: none → pending → {verified, rejected}, verified → expired, etc.

Model: crm_owns​

Less common — typical for operators with custom KYC workflows. CRM admin initiates; platform listens for verdicts.

You implement: outbound KYC endpoints.

You DON'T implement: webhook senders. UCRM rejects inbound kyc.* webhooks with 403 for crm_owns tenants.

POST <your-base>/v1/kyc/initiate​

{
  "tenant_id": "...",
  "player_external_id": "casino_player_001",
  "level": 1,
  "requirements": ["passport", "address_proof"]
}

Response: { ok: true, provider_ref?: "..." } or { ok: false, code, message }.

POST <your-base>/v1/kyc/update​

CRM admin approves / rejects on the CRM side; UCRM informs your platform:

{
  "tenant_id": "...",
  "player_external_id": "casino_player_001",
  "status": "verified",   // or "rejected"
  "level": 1,
  "reason": "documents validated"
}

GET <your-base>/v1/kyc/:player_external_id​

Reconciliation lookup:

{
  "status": "verified",
  "level": 2,
  "last_updated": "..."
}

Model: dual​

Both flows simultaneously — typical for MGA / UK where:

  • Platform does ID verification (level 1, level 2)
  • CRM does affordability checks (level 3)

You implement BOTH the outbound endpoints AND the webhook senders. Each KYC level falls naturally to one side or the other; UCRM doesn't enforce which side handles which level.

Model: none​

No KYC tracked at this tenant. UCRM rejects all KYC webhooks AND doesn't expose KYC admin actions. Useful for unregulated test envs only.

State storage​

Regardless of model, CRM stores:

players.kyc_status    -- none | pending | verified | rejected | expired
players.kyc_level     -- 0..10
players.kyc_history   -- append-only audit JSONB
players.kyc_last_event_at
players.kyc_expires_at

Admin UI renders the timeline directly off kyc_history.