Integration Guide

Overview

Integrate v2client verification into your application using either:

Modal/Iframe Integration - Embed verification in a modal or iframe
Direct Integration - Redirect users to the verification portal

Modal/Iframe Integration

1. Include the SDK

<!-- Include the verification SDK -->
<script src="https://verify.test.okid.io/verification-sdk.js"></script>

<!-- Include modal CSS -->
<link rel="stylesheet" href="https://verify.test.okid.io/modal.css">

2. Initialize the SDK

// Initialize the SDK
const verificationSDK = new VerificationSDK({
  baseUrl: 'https://verify.test.okid.io',
  onSuccess: (data) => {
        console.log('Verification completed:', data);
        // Handle successful verification
    // data.verification_id, data.status ('verified', 'needs_manual_review', etc.)
    },
  onError: (error) => {
    console.error('Verification failed:', error);
        // Handle verification error
    },
  onClose: () => {
    console.log('Verification modal closed');
        // Handle modal close
  },
  onRetryRequested: (data) => {
    console.log('Retry requested:', data);
    // CRITICAL: Generate new verification ID - failed ones cannot be reused
    generateNewVerificationAndRetry();
  }
});

async function generateNewVerificationAndRetry() {
  // Call your server to generate a new verification ID with your API key
  const response = await fetch('/api/generate-verification', { method: 'POST' });
  const { verificationId } = await response.json();
  
  // Start new verification with fresh ID
  verificationSDK.openWithVerificationId(verificationId);
}

3. Open Verification Modal

Option A: Direct Open (User generates verification)

// Let user generate their own verification
document.getElementById('verify-btn').addEventListener('click', () => {
  verificationSDK.openDirect();
});

Option B: Pre-generated Verification ID

// Use server-generated verification ID
async function startVerification() {
  try {
    // Generate verification ID on your server
    const response = await fetch('/api/generate-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    });
    
    const { verificationId } = await response.json();
    
    // Direct verification (skips selection screen)
    verificationSDK.openWithVerificationId(verificationId);
    
    // OR: Show selection screen (QR code + device choice)
    // verificationSDK.openWithVerificationId(verificationId, true);
  } catch (error) {
    console.error('Failed to generate verification:', error);
  }
}

URL Patterns:
• Direct verification: /?verification_id=...
• Selection screen: /?verification_id=...&mode=select

Server-side Setup

Generate Verification ID (Required for Option B)

// Example: Node.js/Express endpoint
app.post('/api/generate-verification', async (req, res) => {
  try {
    const response = await fetch('https://verify.test.okid.io/api/generate-verification', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-SDK-Key': process.env.OKID_API_KEY // Store API key securely on server
      },
      body: JSON.stringify({
        // Optional: Customize verification flow
        modules: {
          document: { allow_file_upload: true },
          liveness: { passive: false },
          form_data: { fields: [...] }
        }
      })
    });

    if (!response.ok) {
      throw new Error('Failed to generate verification');
    }

    const data = await response.json();
    res.json({ verificationId: data.verificationId });
            
        } catch (error) {
    console.error('Verification generation failed:', error);
    res.status(500).json({ error: 'Failed to generate verification' });
  }
});

Direct Integration

For simpler integration, redirect users directly to the verification portal:

Direct Portal Access

// Let user generate verification themselves
window.location.href = 'https://verify.test.okid.io/';

// Direct verification with pre-generated ID (skips selection)
window.location.href = 'https://verify.test.okid.io/?verification_id=' + verificationId;

// Selection screen with pre-generated ID (shows QR + device choice)
window.location.href = 'https://verify.test.okid.io/?verification_id=' + verificationId + '&mode=select';

When to use mode=select:
• Desktop-first applications wanting mobile option
• When you want users to choose their verification device
• For QR code scanning experience with desktop animation

Verification Outcomes

The verification system will return one of these statuses:

verified- Identity successfully verified

needs_manual_review- Requires manual review by your team

rejected- Verification failed

document_expired- Document has expired

Retry Handling

When verification fails in SDK/modal context, the system sends a retry_requested message instead of redirecting to the portal.

Critical: Failed verification IDs cannot be reused. You must generate a new verification ID with your API key when handling retry requests.

Why Retry Handling is Needed

Users coming from operator integrations used a custom API key to create the verification
Simply redirecting to / would lose the operator context
The operator must generate a new verification ID to maintain API key association

Implementation Example

// Complete retry handling implementation
const sdk = new VerificationSDK({
  baseUrl: 'https://verify.test.okid.io',
  onSuccess: (data) => {
    // Verification succeeded
    handleVerificationSuccess(data);
  },
  onRetryRequested: (data) => {
    console.log('Verification failed, retry requested:', data.reason);
    
    // Show loading state to user
    showRetryMessage('Generating new verification...');
    
    // Generate new verification ID server-side
    generateNewVerificationAndRetry();
  }
});

async function generateNewVerificationAndRetry() {
  try {
    // Call your server endpoint that uses your API key securely
    const response = await fetch('/api/generate-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    });
    
    if (!response.ok) {
      throw new Error('Failed to generate new verification');
    }
    
    const { verificationId } = await response.json();
    
    // Start new verification with fresh ID
    sdk.openWithVerificationId(verificationId);
    
  } catch (error) {
    console.error('Retry failed:', error);
    showErrorMessage('Unable to start new verification. Please try again.');
  }
}

function showRetryMessage(message) {
  // Show user-friendly message during retry
  document.getElementById('status').textContent = message;
}

function showErrorMessage(message) {
  // Show error if retry fails
  document.getElementById('error').textContent = message;
}

Troubleshooting

PostMessage events not triggering?

Check browser console for iframe loading errors
Verify the baseUrl is correct
Ensure verification completes successfully
Check for console logs starting with [IFRAME]

Verification data not loading in iframe?

Use /?verification_id=... for direct verification
Use /?verification_id=...&mode=select only if you want the selection screen
Ensure the verification_id was generated recently
Check that your API key has the correct permissions

onRetryRequested not being called?

Ensure you're using the latest version of verification-sdk.js
Check browser console for [SDK] Retry requested messages
Verify the callback is properly set in SDK initialization
Make sure verification actually failed (not just closed by user)