---
url: https://game-engine-io.github.io/enginex-frontend-sdk/flows/kyc.md
---
# 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](/flows/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

```ts
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](/concepts/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](/concepts/compliance-errors#unconfirmed-operation)).

### In the browser

```ts
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)
})
```

```html
<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](/concepts/extensibility) 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:

```ts
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):

```ts
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.

```ts
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](/concepts/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`.

```ts
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 `*Verified` fields.
* **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.
