KYC tracking

Translator note: machine-translated baseline. Needs human review by a native UK speaker. EN source is canonical.

casinocrm.io підтримує чотири KYC ownership моделі — оберіть один раз per tenant, override per-player при необхідності.

Моделі

kyc_model	Хто ініціює	Хто вирішує	Webhooks accepted
platform_owns	Casino платформа	Платформа	Так — kyc.* lifecycle webhooks update CRM state
crm_owns	CRM admin (POST /v1/players/:id/kyc/request)	CRM admin (POST .../approve)	Ні — casinocrm.io відмовляє inbound kyc.* webhooks (403)
dual	Будь-яка сторона	Будь-яка сторона (split by KYC level — basic via platform, source-of-funds via CRM)	Так
none	Ніхто (тільки test envs)	—	Ні

State machine

none → pending → verified
              → rejected
verified → expired (TTL refresh)
verified → pending (level upgrade)
rejected → pending (resubmit)
expired  → pending (re-verify)

Forward-only. Жодного verified → rejected (admin використовує POST .../revoke, який transitions to expired).

Levels

Operator-defined integer 0..10:

• 0 — no KYC
• 1 — basic ID (passport / driver's license)
• 2 — address verification (utility bill)
• 3 — source of funds
• 4+ — operator-specific (enhanced due diligence, тощо)

Storage

players.kyc_status, players.kyc_level, players.kyc_history (append-only JSONB), players.kyc_last_event_at, players.kyc_expires_at (TTL для verified KYC).

Admin actions

POST /v1/players/:id/kyc/request — доступне тільки коли tenant.kyc_model in {crm_owns, dual} AND adapter supports kyc.initiate. Transitions none → pending.

POST /v1/players/:id/kyc/approve — доступне тільки коли tenant.kyc_model in {crm_owns, dual} AND adapter supports kyc.update. Transitions pending → verified. Optional expires_at for TTL.

POST /v1/players/:id/kyc/revoke — завжди доступне (admin override). Transitions current → expired.

Webhook events

Event	from → to
kyc.submitted	none/rejected/expired → pending
kyc.approved	pending → verified
kyc.rejected	pending → rejected
kyc.expired	verified → expired
kyc.level_upgraded	verified → pending (new higher level submission)

History entry shape:

{
  "ts": "2026-05-08T12:00:00Z",
  "from": "pending",
  "to": "verified",
  "level": 1,
  "actor_kind": "platform" | "crm" | "admin",
  "actor_id": "user_abc",
  "reason": "documents accepted",
  "data": { "provider_ref": "..." }
}

Capability mismatch

Якщо ваш tenant pick-ить crm_owns, але adapter не supports kyc.update, admin UI показує warning + disables Approve button. Operators see trade-off + можуть або змінити adapter, або перемкнутись на platform_owns.