Operational details

Purpose and functionality

Customers can create pre-initialised sessions in the admin panel (Available from the header of the session list page) to allow their users to complete verification later. This enables a structured and streamlined verification process by setting up the session in advance with predefined details.

How it works

1. Creating a unique session

• The customer provides basic user information (e.g., name, email, ID details).
• A verification template flow is selected to define the evaluation process.
• The system generates a unique, shareable URL for the session.

2. User access and verification

• The provided link allows the user to access their session and complete the verification process.
• The session remains valid for one week from creation.

3. Handling interruptions and retries

If the verification flow is interrupted (e.g., network failure, user closes the page), the session can be restarted.

A maximum of five retries is allowed for the same session before it is invalidated.

If the session is interrupted but not completed, it remains in an incomplete state and can be resumed using the same link.

Session management

Unique sessions will be visible on the admin panel before the user completes the flow.

The empty or partially finished details are shown before the session evaluation is completed.

If the shareable link is lost, it can be copied again on the session details page.

Key features and limitations

• Pre-configured flow: Ensures consistency in verification steps.
• Convenient user access: The user can complete verification at their convenience.
• Auto-expiration: Sessions automatically expire after one week, reducing security risks.
• Limited retries: Prevents excessive attempts by restricting retries to five times per session.

This approach ensures flexibility for users while maintaining security and verification integrity.

A pre-initialized session is automatically created for incompatible devices. This transferred session can be continued immediately on SEON's hosted web platform and remains valid for one hour.

Transferred sessions have a maximum of 5 attempts. If this limit is reached, the session will be invalidated.

Compared to unique sessions (manually created via the admin panel), transferred sessions are:

• Automatically initiated for non-compatible devices.
• Expected to be completed immediately by the user.
• Limited to a set number of retries before being invalidated.

Webhooks provide real-time notifications about key session events in the SEON IDV flow. They are triggered when a session is completed, abandoned, or manually updated in the Admin Panel, ensuring external systems stay in sync.

Once a webhook is ready, it’s sent immediately (even though polling occurs every 5 seconds), with up to 5 retry attempts on failure. Webhooks can be configured independently of Fraud API endpoints and are fully documented via OpenAPI for easy integration.

• Once the session evaluation is complete, a webhook is triggered to inform the customer's server about the user’s verification status. Polling occurs every 5 seconds; however, if a webhook is ready to be sent, it is dispatched immediately without waiting for the next polling interval.
• The server retries webhook delivery several times if the customer's server does not return a successful response.
• Webhooks are also triggered for any subsequent status changes initiated via the admin panel.
• If a webhook call fails, it can retry at a max of 5 times.
• IDV webhook and Fraud API webhook can be different

Admin panel status updates

• Customers can manually change the session status in the admin panel.
• Each status change automatically triggers a webhook, ensuring that the customer’s system is updated in real-time.

Webhook event types

The following webhook events are sent by the system:

1. idv:session_finished

• Triggered when a session is completed, either successfully, unsuccessfully or when it is abandoned.
• This event indicates that the user has completed all steps in the eKYC process or left the session incomplete.

2. idv:session_status_updated

• Triggered when a session's status is manually modified by an administrator.

Additional links

• OpenAPI documentation
• API reference

Example webhook payload

Below is an example payload for an idv:session_finished event:

{
  "event": "idv:session_finished",
  "date": "2024-08-30T15:55:03.000Z",
  "details": {
    "name": "John Doe",
    "email": "user@example.com",
    "status": "REVIEW",
    "duplicatesFound": false,
    "userId": "1234",
    "platform": "IOS",
    "sessionId": "00000000-0000-0000-0000-000000000000",
    "startedAt": "2024-08-30T14:51:22.991Z",
    "finishedAt": "2024-08-30T14:55:03.000Z",
    "templateId": "00000000-0000-0000-0000-000000000000",
    "phoneNumber": "+000000000",
    "referenceId": "1234",
    "statusDetail": "",
    "timeline": {
      "session": {
        "startedAt": "2024-08-30T14:51:22.991Z",
        "finishedAt": "2024-08-30T14:55:03.000Z"
      },
      "documentVerification": {
        "startedAt": "2024-08-30T14:51:26.901Z",
        "finishedAt": "2024-08-30T14:51:32.000Z"
      },
      "livenessVerification": {
        "startedAt": "2024-08-30T14:52:01.003Z",
        "finishedAt": "2024-08-30T14:52:15.000Z"
      },
      "proofOfAddressVerification": {
        "startedAt": "2024-08-30T14:53:30.429Z",
        "finishedAt": "2024-08-30T14:55:01.000Z"
      }
    },
    "documentCheckResult": {
      "overallResult": "APPROVED",
      "logicCheckResult": "PASS",
      "matchCheckResult": "PASS",
      "formatCheckResult": "NOT_PERFORMED",
      "screenCheckResult": "PASS",
      "photocopyCheckResult": "PASS",
      "handPresenceCheckResult": "FAIL",
      "imageQualityCheckResult": "PASS",
      "photoForgeryCheckResult": "PASS",
      "dataIntegrityCheckResult": "PASS",
      "barcodeAnomalyCheckResult": "NOT_PERFORMED",
      "suspiciousDataCheckResult": "PASS",
      "ageVerificationCheckResult": "NOT_PERFORMED",
      "documentValidityCheckResult": "PASS",
      "securityFeaturesCheckResult": "NOT_PERFORMED"
    },
    "additionalProperties": {
      "additionalProp1": "value1",
      "additionalProp2": "value2",
      "additionalProp3": "value3"
    },
    "dataExtractionResult": {
      "age": 17,
      "gender": "F/M",
      "country": "HU",
      "fullName": "John Doe",
      "documentType": "NATIONAL_ID",
      "documentNumber": "1234567AB",
      "documentIssueDate": "2022-05-08T00:00:00.000Z",
      "documentExpirationDate": "2028-12-03T00:00:00.000Z"
    },
    "livenessVerificationResult": {
      "blinkCheckResult": "NOT_PERFORMED",
      "depthCheckResult": "NOT_PERFORMED",
      "instructionCheckResult": "NOT_PERFORMED",
      "faceMatchingCheckResult": "NOT_PERFORMED",
      "interferenceCheckResult": "NOT_PERFORMED",
      "overallLivenessVerificationResult": "REVIEW"
    },
    "proofOfAddressCheckResult": {
      "overallResult": "APPROVED",
      "addressDocumentCheckResult": "PASS",
      "addressDocumentMustNotBeExpiredCheckResult": "PASS",
      "addressValidationCheckResult": "PASS",
      "fullAddressCheckResult": "PASS",
      "nameMatchCheckResult": "PASS"
    }
  }
}

A session undergoes various checks and evaluations to determine its final status. The possible final states of a session are:

Session status: The current status of the session stored in the database.

Webhook: The status value included in the webhook sent to the customer.

Admin: The session status displayed in the admin panel.

Session Statuses - Admin

PENDING: A session is marked as PENDING if it has already started but is waiting for the user to complete it before the evaluation can begin. If the session is not completed within a specific period, it will be abandoned as described below.

ABANDONED: Unfinished sessions are marked as ABANDONED after a specific period of inactivity. Read more about abandoned sessions here.

INVALIDATED: A session is marked as INVALIDATED in the following cases:

• Malicious files are detected.
• The retry limit for a specific check is reached.
• A required file is not found.

Read more about about invalid sessions here.

REVIEW: A session is placed in REVIEW status if any of its checks have been marked for review.

APPROVED: A session is marked as APPROVED if all its checks receive an approved status.

DECLINED: A session is marked as DECLINED if any of its checks are rejected.

Check evaluation

A session's result is determined based on the results of its individual checks, which in turn are evaluated based on subchecks.

Subcheck behavior: The default behavior is that subchecks affect the overall check result, but there are a few exceptions. Some subchecks serve only as flags and do not impact the final evaluation.

Document checks

The result of document checks is based on these subchecks:

• Name check
• Date of birth verification
• Postal code validation
• Age verification
• Issuing country/state

If the extracted data is of low quality, the overall document check result can be “REVIEW”, even if one or more failing sub-checks would indicate, that the document check failed.

More about document verification here.

Selfie Checks

Selfie checks have specific override rules based on certain conditions:

• If a selfie check is combined with a document check and a face image cannot be extracted, the check is forced into a REVIEW state.
• If face match check is enabled but the reference face image is missing for a standalone selfie check, the check will result in FAIL.

More about selfie checks here.

Partial completion: If the user exits the verification flow prematurely (e.g., closes the app), some files may be uploaded, but not all required data is processed.

Session timeout:

• Unfinished sessions are marked as abandoned after a set period of inactivity.
• Abandoned sessions are treated as declined.

Restarting the verification:

• Users must restart the entire verification flow if their session is abandoned.
• All steps need to be completed successfully to achieve verification.

Session invalidation is a mechanism to ensure security and data integrity by terminating sessions under specific conditions. When a session is invalidated, it is marked as "declined" and cannot be resumed. The user will be notified about the failed session and must restart the entire verification process as a new session.

Causes of session invalidation

Maximum retry limits exceeded:

• Users are given a limited number of retries to complete verification steps.
• If they exceed this limit, the session is invalidated.

Malicious activity:

• Detection of malicious files during document uploads.
• Any activity that violates the SDK's integrity or security policies.

Unexpected errors or behaviour:

• System anomalies or unexpected behaviours during the session.
• For example, interruptions in processing, corrupted uploads, or server-side issues.

Incomplete sessions: If the user abandons the session (e.g., closes the app before completing all steps) and the session times out, it is marked as abandoned and treated as declined.