Identity verification (KYC)
The KYC demo scenario (check the status and upload a document, without exposing the file in the panel) is in Responsible gaming.
The kyc namespace reads the player's identity verification status and sends documents for review. The review is manual, done by the operator's team in the admin panel: there is no external provider and no redirect. All methods require login.
Check the status
const kyc = await enginex.kyc.getStatus()
// {
// level: 'basic',
// status: 'not_started',
// cpfVerified: true,
// documentVerified: false,
// selfieVerified: false,
// addressVerified: false,
// rejectionReason: null,
// updatedAt: null,
// }status | What it means | What to show |
|---|---|---|
not_started | nothing sent yet | the document request |
pending | document received, awaiting review | "We received your documents" |
in_review | being reviewed by the operator's team | "We are reviewing your documents" |
approved | verification approved | the confirmation (and unlock whatever depended on KYC) |
rejected | declined; the reason is in rejectionReason | the reason and the request to resend |
level and status arrive without the gateway prefix (KYC_LEVEL_FULL → 'full', KYC_VERIFICATION_STATUS_IN_REVIEW → 'in_review'). Both types are open unions: 'unspecified' (the service did not fill it in) or a new value can arrive, so handle the default case. With validation: 'warn', a value the SDK does not know arrives as it came from the gateway and is reported in onValidationIssue; with 'strict', the call rejects with VALIDATION_ERROR (see Response validation). rejectionReason and updatedAt are null when the gateway does not provide them (empty text and the date 1970-01-01T00:00:00Z on the wire).
Documents by level
Levels are cumulative. Which level the operator requires (and for what) is the operator's rule: the gateway does not expose it, so the screen decides from the *Verified fields.
level | What has been verified | Documents (documentType) |
|---|---|---|
none | nothing | — |
basic | CPF and email (at sign-up) | — (cpfVerified) |
intermediate | + identity document | rg_front + rg_back, or cnh_front + cnh_back, or passport (documentVerified) |
full | + selfie and proof of address | selfie (selfieVerified) and proof_address (addressVerified) |
The mapping between documents and levels comes from the level descriptions in the compliance service's protobuf; the service itself is not available for checking, so treat it as guidance.
Upload a document
uploadDocument takes the document type and the file (Blob or File) and sends it as multipart (document_type + file). It returns the id of the received document; the status moves to pending (document received, awaiting review) and changes again when the operator's team reviews it. If the gateway responds without confirming receipt (success: false or no id), the call rejects with UNKNOWN (status 201), with the gateway's message when it provides one (otherwise the SDK's): check getStatus and only resend if the document does not show up (see unconfirmed operation).
In the browser
const input = document.querySelector<HTMLInputElement>('#rg-frente')!
input.addEventListener('change', async () => {
const file = input.files?.[0]
if (!file) return
const { documentId } = await enginex.kyc.uploadDocument({ documentType: 'rg_front', file })
showSent(documentId)
})<input id="rg-frente" type="file" accept="image/jpeg,image/png,application/pdf" />The File from the <input> goes to the gateway with its original name. The client's hooks receive only the field name (file), the type and the size of the file, never the original name (which can identify the player) or the content.
In Node
On Node 20+ (Blob and FormData are globals), pass a Blob with the right type:
import { readFile } from 'node:fs/promises'
const bytes = await readFile('./comprovante.pdf')
await enginex.kyc.uploadDocument({
documentType: 'proof_address',
file: new Blob([bytes], { type: 'application/pdf' }),
})Size and format
The SDK does not limit size or format, and neither does the gateway. We recommend up to 4 MB, as JPEG, PNG or PDF: above that, the compliance service probably rejects the file (default gRPC message limit, not verified) with RESOURCE_EXHAUSTED (429). Validate before sending and shrink the image in the app itself (e.g. resize the photo to ~2000 px on the long side):
const MAX_BYTES = 4 * 1024 * 1024
const ACCEPTED = ['image/jpeg', 'image/png', 'application/pdf']
if (file.size > MAX_BYTES || !ACCEPTED.includes(file.type)) {
showError('Upload a JPEG, PNG or PDF up to 4 MB')
return
}A documentType outside the list, or a file that is not a Blob/File, rejects with CONFIGURATION_ERROR before any request (it is an app usage error). The upload is not idempotent: after a network failure (NETWORK_ERROR, TIMEOUT), call getStatus before resending and disable the button while the upload is in progress.
Follow the review
There is no realtime notice of a change in the verification: call getStatus again when the screen opens and, while it is pending or in_review, at a generous interval.
import type { KycStatus } from '@getenginex/sdk'
const waiting = new Set(['pending', 'in_review'])
async function watchKyc(onChange: (status: KycStatus) => void, signal: AbortSignal) {
while (!signal.aborted) {
const kyc = await enginex.kyc.getStatus(undefined, { signal })
onChange(kyc)
if (!waiting.has(kyc.status)) return kyc // approved, rejected, not_started...
await sleep(60_000, signal) // review is manual: minutes or hours
}
}
// Cancelable wait: `abort` ends the wait right away (without holding the screen for up to a minute).
function sleep(ms: number, signal: AbortSignal) {
return new Promise<void>((resolve) => {
const timer = setTimeout(done, ms)
signal.addEventListener('abort', done, { once: true })
function done() {
clearTimeout(timer)
signal.removeEventListener('abort', done)
resolve()
}
})
}With TanStack Query, the same thing is refetchInterval: (q) => (waiting.has(q.state.data?.status ?? '') ? 60_000 : false).
Errors
| Code | When |
|---|---|
CONFIGURATION_ERROR | documentType outside the list, or file that is not a Blob/File (no request) |
INVALID_ARGUMENT (400) | the gateway could not read the multipart or the file, or rejected the type (gateway message) |
RESOURCE_EXHAUSTED (429) | file too large for the compliance service, or rate limit (e.retryAfter) |
UNKNOWN (201) | the gateway responded without confirming receipt (success: false or no id) |
UNAUTHENTICATED (401) | no session |
VALIDATION_ERROR | in 'strict', a level or status the SDK does not know, or an updatedAt that is not a date |
Other compliance service errors arrive with the code preserved, some as HTTP 500: always decide with isEnginexError(error, code), never by status. The codes that other operations return because of KYC (KYC_REQUIRED, KYC_PENDING, KYC_REJECTED, for example on deposit and withdrawal) are in Error codes.
Testing
createMockFetch() already answers GET /kyc/status (level basic, not_started) and accepts the multipart upload like the gateway (201, or 400 INVALID_ARGUMENT with no file or an invalid type); after an upload, the status moves to pending.
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'
const enginex = createEnginexClient({
baseUrl: 'https://gateway.test', // in Node: absolute baseUrl + tenantHost (optional in the browser)
tenantHost: 'casino.test',
fetch: createMockFetch(),
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
await enginex.kyc.uploadDocument({ documentType: 'selfie', file: new Blob(['x'], { type: 'image/jpeg' }) })
await enginex.kyc.getStatus() // { status: 'pending', ... }What the gateway does not offer yet
- Size limit. The gateway does not limit the file nor return its own error for "too large"; the real ceiling is the compliance service's (probably the ~4 MB gRPC default, not verified). Hence the recommendation of up to 4 MB and validation in the app.
- Guaranteed full read. The gateway reads the file with a single read: the document may be stored truncated without an error. If the review rejects an intact file as unreadable, resend it.
- List of uploaded documents. There is no route to list the documents already sent or the status of each one: only the overall status (
getStatus) and the*Verifiedfields. - Starting an external verification.
StartKYC(verification by an external provider with a redirect) has no route in the gateway; the flow is document upload and manual review only. - Realtime. No realtime event announces approval or rejection: follow up with
getStatus. - Idempotency. The upload has no
Idempotency-Key: a resend creates another document.