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 valid API key with the appropriate permissions (see Authentication docs)
A registered user in the system (you will need theiruid)
A webhook endpoint configured in the Ralio Management Portal 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

POST /api/v1/account/users/{uid}/identity-verifications

Response — 201 Created

{
  "createdAt": "<string>",
  "data": {},
  "expiresAt": "<string>",
  "flow": {
    "id": "<string>",
    "tag": "<string>"
  },
  "hostedUrl": "<string>",
  "id": "<string>",
  "state": "<string>",
  "type": "<string>",
  "updatedAt": "<string>"
}

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.

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. 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. Webhook payload:

{
  "id": "36f6bb7e-e5da-4278-9ad8-df64c8c4cd22",
  "event": "kyc_session_verified",
  "timestamp": "2026-03-17T16:35:12.501Z",
  "data": {
    "sessionId": "66062076-d3b7-470b-b5ca-cf9b92ad6b0e",
    "userId": "15299b4e-8af7-4716-8695-0bf1d0579944",
    "entityType": "user"
  }
}

What to do: Wait for the kyc_state_updated event 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. Webhook payload:

{
  "id": "5ebcc965-3d96-4af1-8e75-9c97c26ef6da",
  "event": "kyc_session_manual_review",
  "timestamp": "2026-03-17T16:41:28.447Z",
  "data": {
    "sessionId": "f4456ae8-bf7b-4d48-a2a6-4fd0f3d598e9",
    "userId": "d67f9318-bce0-4600-98fc-e0d98d2b1a31",
    "entityType": "user"
  }
}

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 FAILED. The webhook payload includes a checks array with structured failure reasons. Webhook payload:

{
  "id": "c4f6d7a7-cf31-4ae4-af15-7571c0e7f743",
  "event": "kyc_session_failed",
  "timestamp": "2026-03-17T16:49:37.314Z",
  "data": {
    "sessionId": "43b972aa-88c2-4791-9a7b-7a338e182a3c",
    "userId": "15f8e008-d774-4a0f-bc39-a78c8e4859c9",
    "entityType": "user",
    "checks": [
      {
        "type": "manual_review",
        "state": 2,
        "data": {
          "type": "manual_review",
          "provider": "MOCK",
          "timestamp": "2026-03-17T12:40:24-04:00"
        },
        "reasons": [
          {
            "type": "ManualReview",
            "code": "KYC.DOC.DETERIORATED",
            "message": "Document deteriorated or illegible (stains, tears).",
            "category": "DOC"
          }
        ]
      }
    ]
  }
}

Error CODES

Error Code	Cause (why it fails)	Merchant action (proposed solution)
`KYC.IMG.LIGHT_EXCESS`	Facial capture is overexposed (too much light).	Create a new KYC session and ask the user to retry in uniform lighting, without backlighting.
`KYC.IMG.LIGHT_LOW`	Insufficient lighting / high noise in the selfie.	Create a new KYC session; instruct the user to use a front-facing light source.
`KYC.IMG.FRAME_FACE_CUT`	Face was cut off or out of frame.	Create a new KYC session; ask the user to frame their full face.
`KYC.IMG.LIVENESS_HEAD_CIRCLES_MISSED`	User did not complete the liveness gesture (e.g., head circles).	Create a new KYC session; emphasise following the on-screen instructions.
`KYC.IMG.GENERAL`	Generic capture error (blurry, motion blur, etc.).	Create a new KYC session; resend the correct capture checklist.
`KYC.DOC.EXPIRED`	Identity document is expired.	Create a new KYC session; request a valid, non-expired document.
`KYC.DOC.MISSING_EXPIRY`	Expiry date is not visible in the document photo.	Create a new KYC session; ask for photos where the expiry date is clearly readable.
`KYC.DOC.ONE_SIDE_ONLY`	Only one side of the document was submitted.	Create a new KYC session; require both sides of the document.
`KYC.DOC.CROPPED`	Document is cropped or incomplete in the photo.	Create a new KYC session; ask for a full recapture.
`KYC.DOC.DETERIORATED`	Document is deteriorated or illegible (stains, tears).	Create a new KYC session; request another document in good condition.
`KYC.DOC.INVALID_TYPE`	Document type is not valid for the country or policy.	Create a new KYC session; instruct the user to use an accepted type (national ID, passport, etc.).
`KYC.DOC.DRIVER_LICENSE_NOT_ACCEPTED`	Driver’s license is not accepted.	Create a new KYC session; request a passport or national identity document.
`KYC.DOC.GENERAL`	Generic document error.	Create a new KYC session; send capture guidelines (sharpness, no glare).
`KYC.MISMATCH.NAME`	The name extracted by KYC does not match the name on the created User.	Correct the User’s data to match exactly (normalise accents and name order). If the `kycSession` is `VALIDATED` and the provider allows binding → reuse the session; otherwise → create a new session.
`KYC.MISMATCH.SURNAME`	Surnames do not match (User vs. KYC).	Same as above: update the User and reuse if possible; otherwise, create a new session.
`KYC.MISMATCH.DOB`	Date of birth does not match.	Update the User; reuse only if `VALIDATED` and binding is allowed; otherwise, create a new session.
`KYC.MISMATCH.NATIONALITY`	Nationality on the document differs from the User’s nationality.	Update the User (or review the country/document) and reuse if applicable; otherwise, create a new session.
`KYC.MISMATCH.COUNTRY_SELECTED`	Country selected by the user differs from the document’s country.	Update the User/country to align; reuse if `VALIDATED`, otherwise create a new session.
`KYC.MISMATCH.BUSINESS_REPRESENTATIVE`	Legal representative data does not match the KYC information.	Update the representative’s data and reuse if `VALIDATED`; otherwise, create a new session.
`KYC.SYS.UNDERAGE`	User is a minor according to the document.	Close the case: mark as REJECTED. No recovery path available.
`KYC.SYS.PROVIDER_ERROR`	KYC provider error or timeout.	Automatic retry with backoff. If it persists, open a support ticket.
`KYC.SYS.GENERAL`	Generic system error not attributable to the user.	Retry; if it continues, contact support and include the `correlationId` for traceability.

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:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "kyc_state_updated",
  "timestamp": "2025-06-19T17:14:13.123Z",
  "data": {
    "kycId": 12345,
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "entityType": "user",
    "state": "REGULAR"
  }
}

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".

Full 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

Getting started

Authentication

Users

User verification

Accounts

Payins

Payouts

Transfers

Orders

Ledger

Reference

Overview

IDV Session — Integration Overview

What is an IDV Session?

Prerequisites

Step 1 — Create an IDV Session

Step 3 — Listen for Webhook Events

Session States Reference

Outcome Paths

Approved — `kyc_session_verified`

Manual Review — `kyc_session_manual_review`

Rejected — `kyc_session_failed`

Error CODES

Expired — `kyc_session_expired`

KYC Level & Account Creation

Full Webhook Event Reference

Getting started

Authentication

Users

User verification

Accounts

Payins

Payouts

Transfers

Orders

Ledger

Reference

​IDV Session — Integration Overview

​What is an IDV Session?

​Prerequisites

​Step 1 — Create an IDV Session

​Step 2 — Share the Hosted URL with the User

​Step 3 — Listen for Webhook Events

​Session States Reference

​Outcome Paths

​Approved — kyc_session_verified

​Manual Review — kyc_session_manual_review

​Rejected — kyc_session_failed

​Error CODES

​Expired — kyc_session_expired

​KYC Level & Account Creation

​Full Webhook Event Reference

IDV Session — Integration Overview

What is an IDV Session?

Prerequisites

Step 1 — Create an IDV Session

Step 2 — Share the Hosted URL with the User

Step 3 — Listen for Webhook Events

Session States Reference

Outcome Paths

Approved — `kyc_session_verified`

Manual Review — `kyc_session_manual_review`

Rejected — `kyc_session_failed`

Error CODES

Expired — `kyc_session_expired`

KYC Level & Account Creation

Full Webhook Event Reference