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 |
Notes
kyc_state_updatedandkyc_expiration_warningrefer 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
userorrelated-party.