> ## Documentation Index
> Fetch the complete documentation index at: https://doc.raliopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# IDV Session — Integration Overview

This guide explains the full lifecycle of an Identity Verification (IDV) Session in Ralio, from creation through the final KYC state change that unlocks account creation.

***

## What is an IDV Session?

An IDV (Identity Verification) Session is a single, time-limited verification attempt for a given user. When created, Ralio returns a `hostedUrl` — a ready-to-use verification page that you share with your end user. There is no redirect URL configuration; instead, your backend receives real-time updates via **webhooks** as the session progresses.

Each session has a **7-day expiry window**. If the user does not complete verification within that period, the session expires and a new one must be created.

***

## Prerequisites

Before creating an IDV Session you must have:

* A registered user in the system (you will need their `uid`)
* A webhook endpoint configured in the [Ralio Management Portal](https://portal.raliopay.com/account/webhooks) that subscribes to KYC events

***

## Step 1 — Create an IDV Session

Call the endpoint below to initiate a new verification session for a user.

**Endpoint**

```text theme={null}
POST /api/v1/account/users/{uid}/identity-verifications
```

> **Important:** Store the `id` (session ID) in your system. You will use it to correlate the incoming webhook events with the correct user and session.

***

## Step 2 — Share the Hosted URL with the User

The `hostedUrl` returned in the response is the verification page for the end user. Direct the user to this URL through your product — for example, as a button in your onboarding flow or a link sent via email/SMS.

**There is no configurable redirect URL.** Once the user completes the verification flow on the hosted page, your system will be notified exclusively through webhook events.

```text theme={null}
hostedUrl: "https://verify.raliopay.com/session/abc123..."
```

The session URL remains valid for **7 days** from creation. After that, it expires and you must create a new session.

***

## Step 3 — Listen for Webhook Events

Configure your webhook endpoint to handle the following KYC events.

**Relevant events for IDV Sessions:**

| Event                       | Trigger                                    |
| :-------------------------- | :----------------------------------------- |
| `kyc_session_verified`      | Session successfully verified              |
| `kyc_session_manual_review` | Session sent to manual compliance review   |
| `kyc_session_failed`        | Session rejected                           |
| `kyc_session_expired`       | Session expired before completion          |
| `kyc_state_updated`         | User's KYC level changed (LIGHT → REGULAR) |

***

## Session States Reference

An IDV Session moves through the following states during its lifecycle:

| State         | Code | Description                                            |
| :------------ | :--- | :----------------------------------------------------- |
| `NOT_STARTED` | 1    | Session created, verification not yet begun            |
| `STARTED`     | 2    | User has opened the hosted URL and is verifying        |
| `VERIFIED`    | 3    | All checks passed — session approved                   |
| `REVIEW`      | 4    | Automatic checks inconclusive; sent to manual review   |
| `REJECTED`    | 5    | Session failed — one or more checks refused            |
| `EXPIRED`     | 6    | Session expired before the user completed verification |

***

## Outcome Paths

### Approved — `kyc_session_verified`

All verification checks passed. The session state transitions to `VERIFIED`.

**What to do:** Wait for the `kyc_state_updated` event (see [KYC Level & Account Creation](https://claude.ai/chat/387ca55b-62d6-4e4a-842a-109703bddf20#kyc-level--account-creation)) before unlocking account creation for the user.

***

### Manual Review — `kyc_session_manual_review`

Automatic checks could not conclusively verify the user. The session state transitions to `REVIEW` and is assigned to a compliance officer for manual inspection.

**What to do:** Inform the user that their verification is under review. No action is required on your side — the compliance team will process it. Once they reach a decision, you will receive either a `kyc_session_verified` or `kyc_session_failed` event.

***

### Rejected — `kyc_session_failed`

One or more checks failed. The session state transitions to `REJECTED`. The webhook payload includes a `checks` array with structured failure reasons.

**What to do:** A rejected session is terminal — you cannot retry it. You must **create a new IDV Session** for the user to attempt verification again. Use the `code` and `message` fields to surface a meaningful error message to the user so they understand what went wrong.

***

### Expired — `kyc_session_expired`

The session was not completed within the 7-day window. The session state transitions to `EXPIRED`.

**What to do:** Create a new IDV Session and share the new `hostedUrl` with the user.

***

## KYC Level & Account Creation

Ralio maintains an overall **KYC Level** for each user, independently of individual sessions. The two levels are:

| Level     | Code | Description                                |
| :-------- | :--- | :----------------------------------------- |
| `LIGHT`   | 2    | Basic verification — default initial state |
| `REGULAR` | 1    | Full KYC completed                         |

When a session is successfully verified, Ralio upgrades the user's KYC level from `LIGHT` to `REGULAR` and fires a `kyc_state_updated` event:

> **Account creation is only permitted when the user's KYC level is **`REGULAR`**.** Do not attempt to create an account based on the `kyc_session_verified` event alone — wait for `kyc_state_updated` with `state: "REGULAR"`.

***

## Webhook Event Reference

| Event                       | Session State | Action Required                               |
| :-------------------------- | :------------ | :-------------------------------------------- |
| `kyc_session_verified`      | `VERIFIED`    | Wait for `kyc_state_updated` → `REGULAR`      |
| `kyc_session_manual_review` | `REVIEW`      | Notify user; await compliance decision        |
| `kyc_session_failed`        | `REJECTED`    | Read error codes; create a new IDV Session    |
| `kyc_session_expired`       | `EXPIRED`     | Create a new IDV Session                      |
| `kyc_state_updated`         | —             | If `state = REGULAR`, unlock account creation |