Overview

This document explains how to handle the submissionStatus submission state parameter and various code values returned by AAI KYC iframe, helping you correctly identify user KYC submission status.

Submission Status Parameter

submissionStatus Field

When DV (Document Verification) product completes document submission, or IDV (Identity Verification) product completes document and liveness submission, the iframe will push the following data to your page through message event:

Important Note: submissionStatus = SUBMITTED only indicates KYC materials have been submitted, not that verification passed. Actual verification results need to be determined by the backend Get Result API field.

Status Determination Logic

1. Submitted Status (SUBMITTED)

When submissionStatus === 'SUBMITTED', it indicates user has completed material submission. You can:

• Capture user's material submission action
• Update user review status
• Trigger subsequent business processes

Handling Example:

if (submissionStatus === 'SUBMITTED') {
  console.log('KYC materials submitted');
  updateUserAuditStatus(); // Example: trigger business logic to update user audit status
  return;
}

2. Unsubmitted Status (UNSUBMITTED)

When submissionStatus === 'UNSUBMITTED', handle differently based on the code field:

2.1 Specific Codes Requiring Dedicated Handling

The following codes need separate handling with corresponding business logic:

2.2 Other Codes - Guide to Resubmit

For codes other than the above, they all indicate unsuccessful submission. Recommend guiding user to retry the KYC submission process.

Complete Code Example

window.addEventListener('message', (event) => {
  const { type, code, submissionStatus, shortUrl } = event.data;
  
  if (type === 'complete') {
    // 1. Listen for SUBMITTED status: capture material submission action
    if (submissionStatus === 'SUBMITTED') {
      console.log('KYC materials submitted');
      updateUserAuditStatus(); // Example: trigger business logic to update user audit status
      return;
    }
    
    // 2. Handle UNSUBMITTED status: unsubmitted material scenarios
    if (submissionStatus === 'UNSUBMITTED') {
      switch (code) {
          // 2.1 Specific codes execute corresponding handling logic				
        case 'CAMERA_ISSUE': //camera not supported or can not open camera(This event is sent only when the fallback flow is disabled in your configuration.)
          handleCameraIssue();
          break;
        case 'NOT_SUPPORT': // browser not support(wasm,getUserMedia api not support etc)(This event is sent only when the fallback flow is disabled in your configuration.)
          handleBrowserIssue();
          break;
          
        case 'RESELECT_REGION':
          handleReselectRegion();
          break;
          
        case 'RESELECT_DOC_TYPE':
          handleReselectDocType();
          break;
          
        // 2.2 Other codes guide to resubmit
        default:
          console.log('User did not successfully submit KYC materials');
          guideRetryKycProcess(); // Example: guide user to retry KYC submission process
          break;
      }
      return;
    }
  } else if (type === 'copy') {
    console.log('shortUrl', shortUrl);
  }
});

DV Product (Document Verification)

Submission Scenarios

When user submits single or double-sided document to backend and navigates to result page, the following code is triggered:

Backend Behavior: Directly triggers callback

Non-Submission Scenarios

The following scenarios do not trigger callback, user has not completed submission:

Backend Behavior: Does not trigger callback

IDV Product (Document + Liveness Verification)

Submission Scenarios

When user completes liveness detection submission, the following codes are triggered:

Backend Behavior: Directly triggers callback

Important Notes:

• As long as user completes liveness detection submission, submissionStatus will be SUBMITTED
• Even if codes like LIVENESS_ATTACK, SIMILARITY_FAILED are returned, it still counts as submitted

Non-Submission Scenarios

The following scenarios do not trigger callback, user has not completed submission:

Backend Behavior: Does not trigger callback

Complete Code Reference

DV Product Code List

IDV Product Code List

Key Terminology

• Submission State: User completes operation and successfully submits data to backend, backend triggers callback to return processing result, submissionStatus = SUBMITTED
• Non-Submission State: User operation does not meet submission conditions, backend does not trigger callback, submissionStatus = UNSUBMITTED
• DV: Document Verification
• IDV: Identity Verification (includes document and liveness detection)
• Callback: Backend synchronous callback, used to notify processing results

FAQ

Q: What is the relationship between submissionStatus and code?

• submissionStatus indicates whether submission action was completed (SUBMITTED / UNSUBMITTED)
• code indicates processing result after submission or reason for failure
• submissionStatus = SUBMITTED + code = SUCCESS: KYC data (ID document or liveness check) successfully submitted and under review.
• submissionStatus = SUBMITTED + other codes (e.g., LIVENESS_ATTACK): Submitted but verification failed
• submissionStatus = UNSUBMITTED: Submission not completed, code indicates specific reason

Q: How to determine if KYC verification under review?

• DV Product: submissionStatus = SUBMITTED and code = SUCCESS means document verification under review
• IDV Product: submissionStatus = SUBMITTED and code = SUCCESS means under review
• All other cases indicate verification failed or not submitted

Q: Why is submissionStatus SUBMITTED for LIVENESS_ATTACK?

Because user has completed the submission action of liveness detection, but the verification result determined it as an attack. SUBMITTED means "materials submitted", not "verification passed".

Q: What happens if user exits midway or refreshes the page?

No callback will be triggered, and no message event will occur.

Q: How to handle token expiration (IAM_FAILED)?

1. User submission after session timeout (typically 1 hour) will return this code
2. Recommend regenerating KYC URL
3. Guide user to restart the process

Best Practices

1. Always check both submissionStatus and code: Only by combining both can you accurately understand user status
2. Provide clear user guidance for specific codes: Such as CAMERA_ISSUE, NOT_SUPPORT, etc.