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.stage.okid.io/verification-sdk.js"></script>

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

2. Initialize the SDK

// Initialize the SDK
const verificationSDK = new VerificationSDK({
  baseUrl: 'https://verify.stage.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.stage.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: Attach custom metadata (returned in webhooks)
        extra_data: {
          reference_id: req.body.orderId,
          user_id: req.user.id,
          context: 'account_verification'
        }
      })
    });

    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' });
  }
});

Pro Tip: Use the extra_data field to attach custom metadata (order IDs, user references, etc.) to verifications. This data is stored with the verification and included in webhook notifications, making it easy to match verifications with your internal systems.

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.stage.okid.io/';

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

// Selection screen with pre-generated ID (shows QR + device choice)
window.location.href = 'https://verify.stage.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.stage.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)