iGaming API Integrations

KYC API Integration for Player Onboarding

Player onboarding joins account creation, identity proofing and decisions about what an operator permits the account to do. A KYC integration often sends the player to a hosted verification flow, associates the provider's applicant or session ID with an internal account, and receives asynchronous results through webhooks or status retrieval. These technical results do not independently establish an operator's legal obligations or authorize gambling. Age thresholds, anti-money-laundering controls, sanctions checks, escalation rules and document retention differ by market and licence. This guide separates provider evidence, operator decisions and audit records, then presents the API and failure tests needed for a controlled implementation.

Abstract identity card with verification shield, document-scanning module and secure API servers
Identity verification supplies evidence for an operator-controlled onboarding decision; the provider result is not itself a gaming permission.
On this page

How is KYC verification different from account onboarding?

Account onboarding creates a player identity in the operator's systems. Know Your Customer (KYC) verification is an evidence-gathering and assessment step that may help confirm a claimed identity, age or other required attributes. A provider's approved verification outcome is an input to an operator's eligibility decision, not a universal licence to deposit, play or withdraw. Requirements vary by jurisdiction and business model. [4] [5]

A robust integration treats signup, identity proofing, risk or AML assessment and product permissions as related but separate states. The same player may be able to edit a profile while a review is pending yet remain blocked from restricted operations. Rejected or expired verification should not erase account history or outstanding financial records. [1] [3]

Which systems and identifiers should be mapped?

Typical participants are an account service, jurisdiction and risk rules, an onboarding orchestration backend, a provider API and hosted SDK, a signed webhook receiver, an operator decision service and an audit store. Create a stable mapping between the internal player and the provider's applicant or session ID while keeping integration keys on the backend. [1] [3]

Record or actorPurposeOwnership rule
Player account IDReference the operator identityNever trust a browser-supplied ID
Provider applicant IDGroup provider-side evidenceMap to one permitted account
Verification session IDTrack one capture or reviewDistinct from the account ID
Policy/version IDExplain required checksOperator-controlled configuration
Webhook event IDDetect repeated notificationsDeduplicate before mutation
Decision and audit IDTrack an access outcomeDurable, restricted history

Provider terminology is not interchangeable: one service may separate applicants and review levels while another uses verification sessions and decisions. Retain source identifiers and version each provider adapter. Keep personally identifying fields out of trace URLs and general analytics. [1] [3] [6]

What rules belong before identity collection starts?

Before creating an external verification session, decide which market, product and risk policies apply. Some businesses need different checks for registration, deposits, age or later account activity. FATF guidance explains risk-based customer due diligence in its scope; it is not a global rule that every gaming operator must follow exactly the same workflow. Confirm the operator's actual obligations locally. [4] [5]

  • Resolve the market and operator entity from trusted account context, not an editable country field.
  • Apply documented age, identity, AML and escalation requirements for the specific product and jurisdiction.
  • Select the provider workflow and acceptable document methods before collecting evidence.
  • Provide suitable notice, a lawful processing basis and clear handling of failed or deferred verification.

Do not gather all possible identity attributes by default. The selected checks should be relevant and proportionate; additional screening and biometric processing demand their own legal, security and vendor review. Document who can override a provider result and how manual review works. [5] [6]

What is a typical end-to-end KYC API flow?

An operator backend creates a provider applicant or verification session using approved configuration, receives a short-lived client or hosted-flow reference, and lets the player submit the required evidence in the provider's controlled interface. The provider processes the session and notifies the operator through a webhook; the operator verifies the message, reconciles the current status and applies its access policy. [1] [2] [3]

  1. Create or reuse the intended provider applicant for the authenticated operator player.
  2. Start a scoped verification session and open the approved hosted or SDK flow.
  3. Record provider IDs and the onboarding attempt without putting secret API credentials in the browser.
  4. Validate a signed result notification, read the authoritative state and update operator permissions.
Three-column flow from operator account and KYC session to hosted identity verification and signed webhook, ending with operator access decision and audit
The provider assesses identity evidence; only the operator decides what the verified account may do.

An SDK completion screen or HTTP success from session creation is not a final verification decision. The player can close a browser, the review can continue asynchronously and the same applicant may need extra evidence. Show an honest pending state until the server has a trustworthy result. [2] [3]

How are KYC webhooks authenticated and reconciled?

Verification results frequently arrive asynchronously. Verify the webhook's authenticating signature over the exact raw body using the scheme configured for that provider, validate the expected applicant/session mapping and reject wrong-account references. Sumsub documents HMAC digest checking; other vendors have their own schemes. A trusted transport alone is not sufficient authorization. [2] [7]

  1. Read the raw request and verify the provider-specific signature or authentication proof before accepting it.
  2. Bind its applicant and session IDs to the intended player, market and current verification attempt.
  3. Deduplicate event IDs or the closest stable provider event identity and persist the state transition.
  4. When events are missing, stale or contradictory, query the provider's official status endpoint and reconcile.

Never treat an unverified browser success callback as a reason to unlock gaming operations. Make the webhook receiver idempotent, log only safe metadata and establish a replay or polling path for interruptions. Store secrets in server configuration and rotate them under a planned incident procedure. [1] [2]

How should pending, approved and rejected results affect access?

Verification providers may expose pending, in-review, approved, declined and resubmission states, but their exact values and meanings differ. The operator must normalize each outcome under a documented policy. A positive document check does not automatically resolve age, sanctions, affordability, responsible-gaming or local eligibility requirements. [1] [3] [5]

Normalized stateOperator responseKey safeguard
Not startedOffer required flowNo implied approval
Pending / in reviewRestrict gated operationsPreserve a retry path
Needs resubmissionRequest specific next stepDo not duplicate applicant
Provider approvedEvaluate remaining policyNo automatic global unlock
Rejected / escalatedRestrict and review safelyKeep reason and appeal process

Define exactly which operator features depend on each policy outcome: signup, deposit, wagering, withdrawal and account maintenance may have distinct controls. Keep the approval actor, result timestamp, policy version and rationale auditable without copying all raw evidence to every service. [5] [6]

What privacy, retention and data-sharing controls matter?

Identity documents, extracted attributes and biometric material are unusually sensitive. Design the data flow so the operator receives only attributes required for its lawful purpose, with access restricted to named services and teams. GDPR Article 5 describes purpose limitation, data minimization, storage limitation and security principles for applicable processing; retention must also reflect other binding obligations. [4] [6]

  • Document the controller/processor roles, transfer locations, legal basis and vendor agreements for each market.
  • Prefer status references and minimal verified attributes over unnecessary copies of document images.
  • Encrypt sensitive data, restrict access, avoid verbose logs and redact support/analytics events.
  • Define evidence and decision retention schedules, deletion requests, legal holds and audit access.

Biometrics and automated decision-making may trigger additional legal and procedural requirements; do not infer authorization from the availability of an SDK feature. Treat re-verification and investigations as controlled uses with their own purpose and audit record. [4] [6]

How should failures, repeats and re-verification be handled?

Networks fail between session creation, document submission, review and webhook delivery. A duplicate create request must not silently manufacture unrelated applicants; a repeated decision event must not toggle access incorrectly. Use durable correlation IDs, provider-aware idempotency, status polling where supported and operator-owned state transitions. [1] [2]

  • Handle abandoned sessions and client reconnections without merging different player identities.
  • Deduplicate delayed or repeated callbacks and reject contradictory final states without review.
  • Queue uncertain outcomes for reconciliation and display a clear pending state to the player.
  • Trigger re-verification when policy or reliable evidence requires it, with the old decision preserved.
  • Monitor webhook signature failures, review latency, incomplete capture rates and manual-review backlog.

Plan provider outages, migration of applicants and contract version updates before release. Escalations should distinguish a technical failure, missing document, high-risk review and completed rejection so customer support and compliance teams do not present misleading outcomes. [3] [5]

What should a KYC integration acceptance test cover?

Acceptance testing must cover identity binding and real operator permissions, not merely a verification SDK that opens. Confirm that correct documents can be submitted, provider decisions reach the backend, and restricted capabilities stay locked until a suitable policy decision exists. Exercise every local market and workflow configuration separately.

  1. Enroll a new player, start an approved provider session and verify the ID mapping and successful review.
  2. Attempt to reuse another player's applicant ID or client token; verify authorization failure.
  3. Test pending, extra-evidence, rejected, expired and manual-review states without premature access.
  4. Drop and replay a signed webhook, send an invalid signature, and verify idempotent reconciliation.
  5. Audit minimal data capture, access restrictions, retention rules, alerting and manual escalation.

Before production, obtain approval from integration, security, privacy and relevant compliance owners; freeze test evidence and rehearse routing disablement. The primary success condition is that verified evidence is faithfully mapped into an operator-owned decision without leaking sensitive data or incorrectly unlocking play or payments. [2] [4] [6]

Sources & further reading

Diagram viewer