Two endpoints back the KYC verification flow: one mints the hosted
verification URL your page opens in a popup, one refreshes the contact email on
a verification that’s already underway. Outcomes come back asynchronously via
the kyc_status_changed webhook.
Create a verification session
POST https://{operator}.app.lootboxsolutions.com/api/s2s/kyc/sessions
{
"playerExternalId": "u_8431",
"email": "player@example.com",
"locale": "en",
"returnOrigin": "https://casino.example"
}
Field
Required
Notes
playerExternalId
✅
Your stable opaque player id (1–190 chars).
email
✅
Where the player’s verification emails land (see player emails). Held privately; never appears in URLs or webhooks.
locale
✅
BCP-47-ish code (e.g. en, pt-BR). Language of the hosted verification page.
returnOrigin
—
The exact origin (scheme + host + port) that receives the popup’s completion postMessage. Omit it and the popup posts nothing — you rely on the webhook.
Open kycUrl in a popup window (window.open) — the page
refuses framing, so it cannot go in an iframe.
The URL is valid for 30 minutes (expiresAt) and single-use — the
embedded token is consumed the moment the player opens the page. Mint a fresh
one per click; an expired or reused link shows the player a “link expired”
screen, not an error of yours.
Minting is idempotent-friendly by design: if the player already has an
open PENDING request, that request is reused (its contact fields refresh to
what you just sent) and a new link is issued — any earlier link stops
working. If their latest request was decided (or they never had one), a
fresh request opens, which emits its own PENDING webhook.
the player’s verification is already submitted and awaiting review — nothing for them to redo
validation error
422
malformed input
Update the contact email
Call this when a player changes their account email while a verification is
open, so decision emails keep landing in the right inbox.
POST https://{operator}.app.lootboxsolutions.com/api/s2s/kyc/email
{
"playerExternalId": "u_8431",
"email": "new-address@example.com"
}
Field
Required
Notes
playerExternalId
✅
Same id the session was minted for.
email
✅
The new contact address.
Response — 200
{ "ok": true }
Errors
code
HTTP
when
KYC_NO_OPEN_REQUEST
404
the player has no open (PENDING/SUBMITTED) verification — decided requests are immutable history
KYC_NO_OPEN_REQUEST is a benign outcome, not a failure: it just means
there was nothing to update. Fire this call on every email change without
checking KYC state first and ignore the 404.