> ## 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

> Overview of KYC-related webhook events

## KYC Events

These webhook events notify merchants about changes related to Know Your Customer (KYC) verification, including updates to an entity's overall KYC status and the outcome of individual verification sessions.

## Understanding KYC vs KYC Session

* **KYC**: Represents the overall verification record associated with an entity.
* **KYC Session**: Represents a specific verification attempt or verification flow linked to that KYC record.

## Entity Types

KYC events can be associated with different entity types:

| Entity Type   | Description                       |
| ------------- | --------------------------------- |
| user          | A user verification flow          |
| related-party | A related party verification flow |

## KYC Levels

The overall verification level assigned in the system:

| Level   | Code | Description                     |
| ------- | ---- | ------------------------------- |
| REGULAR | 1    | Full KYC verification completed |
| LIGHT   | 2    | Basic/light KYC verification    |

## KYC Session States

Possible states for an individual verification session:

| State        | Code | Description                                          |
| ------------ | ---- | ---------------------------------------------------- |
| NOT\_STARTED | 1    | Session was created but verification has not started |
| STARTED      | 2    | Verification is currently in progress                |
| VERIFIED     | 3    | Session was successfully verified                    |
| REVIEW       | 4    | Session requires manual review                       |
| REJECTED     | 5    | Session verification failed                          |
| EXPIRED      | 6    | Session expired before completion                    |

## KYC Session Check States

Possible states for individual checks within a session:

| State     | Code | Description                 |
| --------- | ---- | --------------------------- |
| Validated | 1    | Check passed successfully   |
| Refused   | 2    | Check failed or was refused |

## Available Events

| Event                                | Description                                            | Triggered By                        |
| ------------------------------------ | ------------------------------------------------------ | ----------------------------------- |
| kyc\_state\_updated                  | Sent when the overall KYC state changes                | KYC state change                    |
| kyc\_expiration\_warning             | Sent when a KYC is close to expiration                 | KYC nearing expiration              |
| kyc\_session\_verified               | Sent when a KYC session is successfully verified       | Session state: VERIFIED             |
| kyc\_session\_manual\_review         | Sent when a KYC session requires manual review         | Session state: REVIEW               |
| kyc\_session\_failed                 | Sent when a KYC session fails                          | Session state: REJECTED             |
| kyc\_session\_expired                | Sent when a KYC session expires before completion      | Session state: EXPIRED              |
| related\_party.kyc\_session\_created | Sent when a KYC session is created for a related party | New KYC session for a related party |

## Notes

* `kyc_state_updated` and `kyc_expiration_warning` refer to the KYC record itself.
* `kyc_session_*` events refer to the lifecycle of a specific verification session.
* Depending on the flow, events may be associated with `user` or `related-party`.
* `related_party.kyc_session_created` only applies to related parties of business users and carries the full related-party profile in addition to the session info.