Compliance and Reporting API

1) Purpose

• Collection and validation of events (gaming/payment/authentication) for AML/Responsible Gaming (RG).
• Inspections (KYC/KYB, sanctions/PEP, sources of funds, age).
• Regulatory reporting (periodic and ad-hoc) by market.
• Maintaining audit logs and executing Legal Hold.
• Data exchange with providers (PSP, KYC exchanges, sanctions lists) and state portals.

The result: reduced operational overhead, faster reporting, traceability, and local compliance.

2) Scope

Identification and verification: KYC/KYB statuses, verification levels, documents.
AML/sanctions/PEP: screening, transaction monitoring, STR/SAR, alerts.
Responsible play (RG): limits, self-exclusion, "cool-off," behavioral risk scales.
Payments and transactions: deposits/withdrawals, chargeback, bonus mechanics.
Reporting: GGR/taxes, player/session registries, marketing restrictions, security incidents.
Audit and storage: immutable logs (WORM), Legal Hold, DSAR/RTBF.

3) Data consumers and producers

Consumers: Regulators, Internal Compliance/Risk, BI/DWH, SecOps, Finance.
Manufacturers: fronts/backends iGaming, PSP/aquiring, KYC providers, anti-fraud, CRM, affiliate networks.

4) Architectural reference

1. Edge/API-шлюз (mTLS, OAuth2/OIDC, rate-limit, WAF).
2. Compliance service (business rules, provider orchestration, normalization).
3. Event bus (Kafka/Redpanda) - fan-out in SIEM/DWH/archive.

• Online (PostgreSQL/ClickHouse) for quick queries/aggregations.
• Archive (Object Storage + WORM) for immutable artifacts and reports.
• 5. Audit and observability: OpenTelemetry (trace_id), indexing logs, dashboards.
• 6. Provider connectors: KYC, sanctions, RG modules, state portals with e-signature.

5) Main endpoints (v1)

5. 1 KYC/KYB and sanctions

'POST/v1/kyc/check '- KYC check request (idempotent).
'GET/v1/kyc/{ user _ id }/status' - current level and expiration date.
'POST/v1/sanctions/screen '- sanction/PEP screening.
'GET/v1/sanctions/{ user _ id }/hits' - matches/escalations.

5. 2 AML and Transaction Monitoring

'POST/v1/aml/transaction '- sending an event (deposit/within/bet/payout).
`GET /v1/aml/alerts? state = open '- open alerts/cases.
'POST/v1/aml/str '- formation and submission of STR/SAR (by market).

5. 3 Responsible Gaming (RG)

'POST/v1/rg/self-exclusion '- set/remove self-exclusion.
'GET/v1/rg/limits/{ user _ id} '- limits (deposit/rate/time).
'POST/v1/rg/assess' - behavior risk assessment.

5. 4 Reporting and registries

'POST/v1/reports/generate '- report generation (type, period, jurisdiction).
'GET/v1/reports/{ report _ id} '- status, artifact download (PDF/CSV/JSON), hash.
'GET/v1/registers/{ type} '- registries (players, sessions, bonuses, GGR) with pagination.

5. 5 Audit and legal transactions

'GET/v1/audit/events' - selection of events (filter by ECS/OCSF fields).
'POST/v1/legal/hold '- set/remove Legal Hold on the object/folder.
'POST/v1/privacy/dsar '- start DSAR, statuses, export packets.

6) Data models (abbreviated)

6. 1 Transaction Event (JSON)

json
{
"idempotency_key": "trx-8b1a9953",
"timestamp": "2025-11-01T16:02:11Z",
"user": {"id":"U-12345","dob":"1999-04-21","country":"EE"},
"transaction": {
"id": "T-778899",
"type": "deposit",
"amount": {"value": 200. 00, "currency": "EUR"},
"method": "card",
"psp_ref": "PSP-222-ABC"
},
"context": {
"ip": "198. 51. 100. 10",
"device_id": "d-9af0",
"session_id": "s-2233",
"trace_id": "f4c2..."
},
"labels": {"market": "EE", "affiliate": "A-77"}
}

6. 2 KYC result

json
{
"user_id": "U-12345",
"level": "L2",
"status": "verified",
"expires_at": "2026-04-21",
"checks": [
{"type":"document","result":"pass"},
{"type":"liveness","result":"pass"},
{"type":"pep_sanctions","result":"no_hit"}
],
"provider": {"name":"KYCX","reference":"KYCX-4455"}
}

6. 3 Report description

json
{
"report_id": "RPT-EE-GGR-2025Q3",
"type": "ggr_quarterly",
"jurisdiction": "EE",
"period": {"from":"2025-07-01","to":"2025-09-30"},
"status": "ready",
"artifact": {
"format": "CSV",
"size_bytes": 183442,
"sha256": "c9b1f...e21",
"download_url": "urn:reports:RPT-EE-GGR-2025Q3"
},
"notes": "Rounded to cents; FX=ECB daily"
}

7) Security and access

Authentication: OAuth2/OIDC (client credentials, JWT), optional mTLS.
Authorization: RBAC/ABAC; separate scopes by domain ('aml: write', 'kyc: read', 'reports: generate').
Encryption: TLS 1. 2+ in-transit; at-rest via KMS/CMK; JWE for sensitive fields.
PII minimization: store minimum; Mask PAN/IBAN aliasing'user. pseudo_id`.
Access log: audit of all reads of "sensitive" endpoints, alerts for mass uploads.
Legal Hold and retention: WORM storage for reports and STR; 5-7 year retention policies (by market).

8) Versioning and compatibility

URI versioning: '/v1 ', '/v2'; minor changes - through expandable fields.
Deprecation-policy: ≥ 6-12 months of support; headlines' Sunset ',' Deprecation '.
Schemes: JSON Schema + OpenAPI; contracts are validated in CI.
Migrations: adapters/feature-flags, two-way compatibility for the transition period.

9) Reliability: idempotency and "exactly once"

Idempotency-Key in'POST '(store keys ≥ 24-72 hours).
At-least-once delivery via bus + receive deduplication (event id/hash).
Outbox/Inbox-pattern for integrations, retrai with exponential pause and jitter.
Order: user _ id/account _ id partitioning keys for determinism.

10) Pagination, filters, search

Pagination: cursor-based ('page _ token', 'limit <= 1000').
Filters: by jurisdiction, period, status, provider, risk assessment.
Full-text search for audit/registries (limited subset of fields).
Export: asynchronous, size limit, preparing an archive with a hash signature.

11) Restrictions and quotas

Rate-limits per client/route (e.g. 100 rps burst, 1000 rpm sustained).
Budget-limits on heavy reports (credits/day).
N + 1 protection: batches and aggregated endpoints.
Limitation of the depth of historical samples (for example, ≤ 24 months online, hereinafter referred to as the archive).

12) Dashboards and SLOs

Ingest lag p95 <30 sec; KYC success> 99%; STR-SLA - dispatch ≤ 24 hours.
API ≥ 99 availability. 9%; Latency p95 <300 ms for reading; <800 ms for recording.
Cost/GB storage of reports; Ack-rate notifications to regulators.
Widgets: AML alert heat map, KYC funnel, country reports release, STR queue.

13) Jurisdictions: Mapping and Patterns

Market report templates (fields, formats, frequency): 'EE', 'LT', 'LV', 'RO', 'MT', 'UK', etc.
Term mapping (GGR/NGR, bonuses, deposit limits, age control).
Localization of timezones/calendars; Fix the FX source Impact DST label.
Schema directory: 'reports/{ jurisdiction }/{ type }/{ version} .schema. json`.

14) Error handling (single format)

json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"request_id": "req-7f91",
"hint": "Reduce RPS or request higher quota",
"retry_after": 30
}
}

Частые коды: `INVALID_SCHEMA`, `NOT_AUTHORIZED`, `LEGAL_HOLD_ACTIVE`, `PROVIDER_TIMEOUT`, `REPORT_NOT_READY`.

15) Testing and certification

Contract tests (OpenAPI → generating test clients).
Fixture sets by jurisdiction, golden-files for reporting.
"Black lists" of PII fields in the logs; static analysis of secret leaks.
Regular DR exercises to restore report archives.

16) Examples

16. 1 Report generation

Inquiry

http
POST /v1/reports/generate
Content-Type: application/json
Authorization: Bearer <token>

json
{
"type": "ggr_monthly",
"jurisdiction": "EE",
"period": {"from":"2025-10-01","to":"2025-10-31"},
"format": "CSV",
"notify": ["compliance@company"],
"parameters": {"include_bonus_breakdown": true}
}

Answer

json
{"report_id":"RPT-EE-GGR-2025-10","status":"processing","eta_seconds":120}

16. 2 STR/SAR send

json
{
"case_id": "AML-2025-0091",
"user_id": "U-12345",
"reason": "Structuring deposits under threshold",
"evidence": ["txn:T-778899","txn:T-778900"],
"attachments": ["urn:doc:kyc:U-12345:v3"],
"jurisdiction": "EE"
}

16. 3 Self-exclusion

json
{
"user_id":"U-12345",
"type":"national_register",
"action":"enable",
"effective_from":"2025-11-01",
"effective_to":"2026-11-01"
}

17) Built-in auditing and immutability

Autologation: 'request _ id', 'trace _ id', calling client, scope.
Signing report packages (SHA-256) + hash registry; periodic anchoring.
WORM archive for regulatory uploads and STR.
History of rule and template configurations (policy change log ↔ link).

18) Processes and RACI (in brief)

R: Compliance Platform Team (Development/Operations).
A: Head of Compliance/CISO (policies, budgets, priorities).
C: Legal/DPO, Finance, Architecture, Data.
I: Product, Support, Partners (PSP/KYC).

19) Implementation Roadmap

1. '/v1/kyc/check ', '/v1/aml/transaction', '/v1/reports/generate '(2-3 key patterns).

2. OAuth2 + rate-limit + baseline idempotency.

3. Archive of reports in Object Storage with hash signature.

4. SLO dashboard and task queues.

• Jurisdictional templates (5-8 markets), STR/SAR, RG-endpoints, DSAR.
• Provider aggregation (CUS/sanctions), retrai, dedupe.
• Legal Hold policies, WORMs, extended roles.

• Rule-as-Code for reports/AML rules, change simulator.
• Multi-tenancy (B2B2C, brands/skins), quotas and billing.
• Sandbox and certification for external integrators.

20) Typical errors and how to avoid them

Divergence of schemes by market: centralized directory, auto-lint schemes.
No idempotency - Type'idempotency _ key'and the deduplication window.
Secrets in the logs: ingest filters, static analysis.
Long online reports: do asynchronously with status-pulling and notifications.
Weak RBAC: post 'read _ reports', 'generate _ reports', 'admin'.
Currency/timezone: fix 'fx _ source', 'timezone', store UTC.

21) Glossary (brief)

KYC/KYB - identification of physical/legal persons.
AML/STR/SAR - anti-laundering/suspicious activity/report.
RG is a responsible game.
GGR/NGR - Gross/Net Gaming Revenue.
WORM - write-once storage.
Rule-as-Code - rules as code with tests/versioning.

22) Bottom line

The compliance and reporting API is a stable, secure and standardized layer between iGaming operations and regulatory requirements. Adherence to the principles from this article (strict schemes, secure integration, idempotency, immutable auditing, jurisdictional templates and SLOs) ensures predictability, fast passage of audits and risk mitigation in key markets.