Testing Identity Verification Systems: KYC, Document Scanning, and Selfie Matching

Testing Identity Verification Systems: KYC, Document Scanning, and Selfie Matching

Identity verification (IDV) systems are among the hardest things to test well. You're dealing with third-party APIs that charge per call, real government documents you can't share across test environments, probabilistic ML models that score rather than pass/fail, and regulatory compliance requirements that make cutting corners genuinely dangerous. This guide covers practical strategies for testing KYC flows, document verification, selfie matching, and the edge cases that expose real bugs.

Why IDV Testing Is Uniquely Difficult

Most API testing problems boil down to: "send a request, assert the response." IDV breaks that pattern in several ways:

  1. Real documents are sensitive. You can't store real passport scans in a test fixture repo.
  2. Third-party APIs are expensive. Onfido charges per check. Jumio charges per verification. You cannot run these on every CI build.
  3. Results are probabilistic. A "clear" result from an AI-based document check means the model was confident enough — not that it was definitely correct.
  4. Regulatory risk is real. A broken KYC flow in production can mean fines, not just bugs.

The solution is a layered testing strategy: mock the third-party layer heavily, test your own orchestration logic thoroughly, and reserve real API calls for targeted integration tests.


Layer 1: Mocking Third-Party IDV APIs

Mocking Onfido

Onfido's API follows a predictable pattern: create an applicant, upload documents, create a check, poll for results. You can mock the entire chain.

// onfido-mock.js
const mockApplicants = new Map();
const mockChecks = new Map();

function createMockOnfidoServer(app) {
  // Create applicant
  app.post('/v3.6/applicants', (req, res) => {
    const id = `applicant_${Date.now()}`;
    const applicant = { id, ...req.body, created_at: new Date().toISOString() };
    mockApplicants.set(id, applicant);
    res.status(201).json(applicant);
  });

  // Upload document
  app.post('/v3.6/documents', (req, res) => {
    const docId = `doc_${Date.now()}`;
    res.status(201).json({
      id: docId,
      applicant_id: req.body.applicant_id,
      type: req.body.type || 'passport',
      side: req.body.side || 'front',
      created_at: new Date().toISOString(),
    });
  });

  // Create check — this is where you control the outcome
  app.post('/v3.6/checks', (req, res) => {
    const checkId = `check_${Date.now()}`;
    const scenario = req.headers['x-test-scenario'] || 'clear';

    const check = {
      id: checkId,
      applicant_id: req.body.applicant_id,
      status: 'complete',
      result: scenario === 'fraud' ? 'consider' : 'clear',
      results_uri: `https://dashboard.onfido.com/checks/${checkId}`,
      report_ids: [`report_${Date.now()}`],
    };

    mockChecks.set(checkId, check);
    res.status(201).json(check);
  });

  // Get check status
  app.get('/v3.6/checks/:checkId', (req, res) => {
    const check = mockChecks.get(req.params.checkId);
    if (!check) return res.status(404).json({ error: 'check not found' });
    res.json(check);
  });
}

module.exports = { createMockOnfidoServer };

The key design decision here is the x-test-scenario header. Your test suite sends this to control the mock's behavior without changing application code.

// onfido.test.js
const axios = require('axios');

describe('Onfido document verification', () => {
  test('marks user as verified on clear result', async () => {
    const applicant = await axios.post('/api/kyc/start', {
      userId: 'user_123',
      documentType: 'passport',
    });

    // Inject scenario via internal header (stripped before forwarding to real Onfido)
    const checkResult = await axios.post(
      '/api/kyc/submit-document',
      { applicantId: applicant.data.onfidoApplicantId, documentBase64: 'fake_base64' },
      { headers: { 'x-test-scenario': 'clear' } }
    );

    expect(checkResult.data.verificationStatus).toBe('approved');
    
    const user = await axios.get('/api/users/user_123');
    expect(user.data.kycStatus).toBe('verified');
    expect(user.data.kycCompletedAt).toBeDefined();
  });

  test('blocks user on consider result and queues manual review', async () => {
    const applicant = await axios.post('/api/kyc/start', { userId: 'user_456', documentType: 'passport' });
    const checkResult = await axios.post(
      '/api/kyc/submit-document',
      { applicantId: applicant.data.onfidoApplicantId, documentBase64: 'fake_base64' },
      { headers: { 'x-test-scenario': 'fraud' } }
    );

    expect(checkResult.data.verificationStatus).toBe('manual_review');
    
    const reviewQueue = await axios.get('/api/admin/kyc-review-queue');
    expect(reviewQueue.data.items.some(i => i.userId === 'user_456')).toBe(true);
  });
});

Mocking Stripe Identity

Stripe Identity is often easier to mock because Stripe provides test mode with specific test files that trigger known outcomes. But for unit tests, you still want a local mock.

# stripe_identity_mock.py
from flask import Flask, request, jsonify
import uuid
import time

app = Flask(__name__)
verification_sessions = {}

SCENARIO_OUTCOMES = {
    'verified': {'status': 'verified', 'last_error': None},
    'requires_input': {'status': 'requires_input', 'last_error': {'code': 'document_expired', 'reason': 'The provided identity document has expired.'}},
    'processing': {'status': 'processing', 'last_error': None},
}

@app.route('/v1/identity/verification_sessions', methods=['POST'])
def create_session():
    session_id = f'vs_{uuid.uuid4().hex[:16]}'
    scenario = request.headers.get('X-Test-Scenario', 'verified')
    
    session = {
        'id': session_id,
        'object': 'identity.verification_session',
        'client_secret': f'{session_id}_secret_{uuid.uuid4().hex[:8]}',
        'created': int(time.time()),
        'status': 'requires_input',
        'type': request.form.get('type', 'document'),
        '_test_scenario': scenario,  # stored for later retrieval
    }
    verification_sessions[session_id] = session
    return jsonify(session), 200

@app.route('/v1/identity/verification_sessions/<session_id>', methods=['GET'])
def get_session(session_id):
    session = verification_sessions.get(session_id)
    if not session:
        return jsonify({'error': {'message': 'No such verification_session'}}), 404
    
    scenario = session.get('_test_scenario', 'verified')
    outcome = SCENARIO_OUTCOMES.get(scenario, SCENARIO_OUTCOMES['verified'])
    
    response = {**session, **outcome}
    response.pop('_test_scenario', None)
    return jsonify(response), 200

@app.route('/v1/identity/verification_sessions/<session_id>/redact', methods=['POST'])
def redact_session(session_id):
    if session_id in verification_sessions:
        verification_sessions[session_id]['redaction'] = {'status': 'redacted'}
    return jsonify({'id': session_id, 'redaction': {'status': 'redacted'}}), 200

Layer 2: Testing Document Verification Logic

Document verification typically involves:

  1. Image quality checks (blur, glare, crop)
  2. Document authenticity checks (MRZ validation, security features)
  3. Data extraction (name, DOB, expiry)
  4. Cross-field validation (extracted data vs. user-supplied data)

Your application code wraps the third-party call and adds business logic. That logic is where bugs live, and it's fully unit-testable.

// document-validator.js
function validateExtractedDocument(extracted, userSupplied) {
  const errors = [];

  // Check expiry
  const expiry = new Date(extracted.expiryDate);
  if (expiry < new Date()) {
    errors.push({ code: 'DOCUMENT_EXPIRED', field: 'expiryDate', value: extracted.expiryDate });
  }

  // Name matching — fuzzy because OCR isn't perfect
  const nameMatch = fuzzyNameMatch(extracted.fullName, userSupplied.fullName);
  if (nameMatch < 0.85) {
    errors.push({
      code: 'NAME_MISMATCH',
      extracted: extracted.fullName,
      supplied: userSupplied.fullName,
      confidence: nameMatch,
    });
  }

  // DOB matching — exact
  if (extracted.dateOfBirth !== userSupplied.dateOfBirth) {
    errors.push({
      code: 'DOB_MISMATCH',
      extracted: extracted.dateOfBirth,
      supplied: userSupplied.dateOfBirth,
    });
  }

  return { valid: errors.length === 0, errors };
}

module.exports = { validateExtractedDocument };
// document-validator.test.js
const { validateExtractedDocument } = require('./document-validator');

describe('validateExtractedDocument', () => {
  const validBase = {
    extracted: {
      fullName: 'JOHN WILLIAM SMITH',
      dateOfBirth: '1990-03-15',
      expiryDate: '2028-06-30',
    },
    userSupplied: {
      fullName: 'John Smith',
      dateOfBirth: '1990-03-15',
    },
  };

  test('passes a valid document where names fuzzy-match', () => {
    const result = validateExtractedDocument(validBase.extracted, validBase.userSupplied);
    expect(result.valid).toBe(true);
    expect(result.errors).toHaveLength(0);
  });

  test('rejects an expired document', () => {
    const extracted = { ...validBase.extracted, expiryDate: '2022-01-01' };
    const result = validateExtractedDocument(extracted, validBase.userSupplied);
    expect(result.valid).toBe(false);
    expect(result.errors[0].code).toBe('DOCUMENT_EXPIRED');
  });

  test('rejects when DOB does not match', () => {
    const userSupplied = { ...validBase.userSupplied, dateOfBirth: '1991-03-15' };
    const result = validateExtractedDocument(validBase.extracted, userSupplied);
    expect(result.valid).toBe(false);
    expect(result.errors[0].code).toBe('DOB_MISMATCH');
  });

  test('rejects when name confidence is below threshold', () => {
    const userSupplied = { ...validBase.userSupplied, fullName: 'Jane Doe' };
    const result = validateExtractedDocument(validBase.extracted, userSupplied);
    expect(result.valid).toBe(false);
    expect(result.errors[0].code).toBe('NAME_MISMATCH');
  });

  test('returns all errors when multiple fields fail', () => {
    const extracted = { ...validBase.extracted, expiryDate: '2020-01-01' };
    const userSupplied = { ...validBase.userSupplied, dateOfBirth: '1995-01-01', fullName: 'Nobody Real' };
    const result = validateExtractedDocument(extracted, userSupplied);
    expect(result.errors.length).toBeGreaterThanOrEqual(2);
  });
});

Layer 3: Test Data Strategies

Synthetic Document Images

You need document images for integration tests without using real documents. Options:

Option A: Vendor-provided test assets. Onfido, Jumio, and Stripe all provide test images in their sandboxes. Use these for integration tests against sandbox environments.

Option B: Generated images. For unit tests at the image-processing layer, generate synthetic images programmatically.

# generate_test_document.py
from PIL import Image, ImageDraw, ImageFont
import io

def generate_test_passport_image(
    name="TEST USER",
    dob="1990-01-01",
    expiry="2030-12-31",
    doc_number="X12345678",
    blur=False,
    add_glare=False,
):
    """Generate a synthetic passport-like image for testing image quality checks."""
    img = Image.new('RGB', (1000, 700), color=(0, 80, 40))
    draw = ImageDraw.Draw(img)

    # Document fields
    draw.text((50, 100), f"PASSPORT", fill='gold')
    draw.text((50, 180), f"Surname / Nom: {name.split()[-1]}", fill='white')
    draw.text((50, 220), f"Given Names: {' '.join(name.split()[:-1])}", fill='white')
    draw.text((50, 260), f"Date of Birth: {dob}", fill='white')
    draw.text((50, 300), f"Date of Expiry: {expiry}", fill='white')
    draw.text((50, 340), f"Document No: {doc_number}", fill='white')

    # MRZ line (simplified)
    mrz_line = f"P<TEST{name.upper().replace(' ', '<')}"
    draw.text((50, 600), mrz_line[:44].ljust(44, '<'), fill='white', font=ImageFont.load_default())

    if blur:
        from PIL import ImageFilter
        img = img.filter(ImageFilter.GaussianBlur(radius=4))

    if add_glare:
        glare = Image.new('RGBA', img.size, (255, 255, 255, 0))
        glare_draw = ImageDraw.Draw(glare)
        glare_draw.ellipse([300, 100, 700, 400], fill=(255, 255, 255, 120))
        img = Image.alpha_composite(img.convert('RGBA'), glare).convert('RGB')

    buf = io.BytesIO()
    img.save(buf, format='JPEG', quality=85)
    return buf.getvalue()

Test Fixture Catalog

Maintain a fixture catalog that maps scenario names to test inputs:

// fixtures/idv-scenarios.js
module.exports = {
  VALID_PASSPORT: {
    documentType: 'passport',
    imageBase64: require('./images/valid-passport.b64'),
    expectedResult: 'clear',
    userData: { fullName: 'Test User', dateOfBirth: '1990-01-01' },
  },
  EXPIRED_PASSPORT: {
    documentType: 'passport',
    imageBase64: require('./images/expired-passport.b64'),
    expectedResult: 'consider',
    expectedErrorCode: 'DOCUMENT_EXPIRED',
    userData: { fullName: 'Test User', dateOfBirth: '1990-01-01' },
  },
  BLURRY_DOCUMENT: {
    documentType: 'driving_licence',
    imageBase64: require('./images/blurry-licence.b64'),
    expectedResult: 'consider',
    expectedErrorCode: 'IMAGE_QUALITY_TOO_LOW',
    userData: { fullName: 'Test User', dateOfBirth: '1985-06-15' },
  },
  MISMATCHED_NAME: {
    documentType: 'passport',
    imageBase64: require('./images/valid-passport.b64'),
    expectedResult: 'consider',
    userData: { fullName: 'Completely Different Person', dateOfBirth: '1990-01-01' },
  },
};

Layer 4: KYC Flow End-to-End Testing

KYC flows typically span multiple steps: document upload, selfie capture, liveness check, result polling. End-to-end tests should cover the full state machine.

// kyc-flow.e2e.test.js
const { chromium } = require('playwright');

describe('KYC verification flow', () => {
  let browser, page;

  beforeAll(async () => {
    browser = await chromium.launch();
  });

  afterAll(async () => {
    await browser.close();
  });

  beforeEach(async () => {
    page = await browser.newPage();
    // Intercept Onfido SDK calls and return controlled responses
    await page.route('**/v3.6/checks', route => {
      route.fulfill({
        status: 201,
        contentType: 'application/json',
        body: JSON.stringify({
          id: 'check_test_123',
          status: 'complete',
          result: 'clear',
        }),
      });
    });
  });

  test('completes verification and unlocks account features', async () => {
    await page.goto('/verify-identity');
    
    // Step 1: Document type selection
    await page.click('[data-testid="document-type-passport"]');
    await page.click('[data-testid="continue-btn"]');

    // Step 2: Document upload
    await page.setInputFiles('[data-testid="document-upload"]', 'fixtures/images/valid-passport.jpg');
    await page.click('[data-testid="upload-submit-btn"]');

    // Step 3: Selfie capture — mock the camera
    await page.evaluate(() => {
      window.__MOCK_SELFIE_RESULT = { status: 'success', matchScore: 0.95 };
    });
    await page.click('[data-testid="take-selfie-btn"]');
    await page.click('[data-testid="confirm-selfie-btn"]');

    // Step 4: Assert success state
    await page.waitForSelector('[data-testid="verification-success"]', { timeout: 10000 });
    expect(await page.textContent('[data-testid="verification-status"]')).toContain('Verified');

    // Step 5: Assert gated feature is now accessible
    await page.goto('/dashboard');
    const withdrawBtn = page.locator('[data-testid="withdraw-btn"]');
    await expect(withdrawBtn).not.toHaveAttribute('disabled');
  });

  test('shows manual review state when check returns consider', async () => {
    await page.route('**/v3.6/checks', route => {
      route.fulfill({
        status: 201,
        contentType: 'application/json',
        body: JSON.stringify({ id: 'check_test_456', status: 'complete', result: 'consider' }),
      });
    });

    await page.goto('/verify-identity');
    await page.click('[data-testid="document-type-passport"]');
    await page.click('[data-testid="continue-btn"]');
    await page.setInputFiles('[data-testid="document-upload"]', 'fixtures/images/valid-passport.jpg');
    await page.click('[data-testid="upload-submit-btn"]');

    await page.waitForSelector('[data-testid="verification-pending"]', { timeout: 10000 });
    expect(await page.textContent('[data-testid="verification-message"]'))
      .toContain('under review');
  });
});

Edge Cases You Must Not Skip

These are the cases most teams discover in production rather than in tests:

Scenario Why It Breaks How to Test
Expired document Expiry parsing fails on edge dates (e.g., last day of month) Fixture with expiry = today, yesterday, exactly 1 year ago
Name with hyphens or accents OCR often drops or mangles them; fuzzy match threshold may reject valid users Fixtures: O'Brien, García, van der Berg
Document from non-Latin script OCR returns romanized version; name comparison against user's Latin input fails Arabic, Cyrillic, CJK passport fixtures
Partial document in frame Image cropping before submission cuts off MRZ Generate image with MRZ outside crop boundary
Liveness check in low light Selfie match scores drop; real users fail on valid selfies Brightness-reduced selfie fixtures
Multiple retries exhausted Does the system lock the session? Can the user start fresh? Simulate 3 consecutive failures
Webhook arrives before poll Race condition: result webhook fires before app records the check ID Integration test with deliberate ordering delay
// edge-cases.test.js
describe('document expiry edge cases', () => {
  const today = new Date().toISOString().split('T')[0];
  const yesterday = new Date(Date.now() - 86400000).toISOString().split('T')[0];
  const tomorrow = new Date(Date.now() + 86400000).toISOString().split('T')[0];

  test.each([
    [yesterday, false, 'DOCUMENT_EXPIRED'],
    [today, false, 'DOCUMENT_EXPIRED'],  // expired ON today should be rejected
    [tomorrow, true, null],
  ])('expiry %s → valid=%s', (expiryDate, expectedValid, expectedCode) => {
    const result = validateExtractedDocument(
      { fullName: 'TEST USER', dateOfBirth: '1990-01-01', expiryDate },
      { fullName: 'Test User', dateOfBirth: '1990-01-01' }
    );
    expect(result.valid).toBe(expectedValid);
    if (expectedCode) {
      expect(result.errors.some(e => e.code === expectedCode)).toBe(true);
    }
  });
});

Webhook Testing

Most IDV providers deliver results via webhooks rather than synchronous responses. Test the webhook handler independently.

# test_onfido_webhook.py
import pytest
import hmac
import hashlib
import json
from app import create_app

@pytest.fixture
def client():
    app = create_app(testing=True)
    with app.test_client() as client:
        yield client

def sign_payload(payload: bytes, secret: str) -> str:
    return hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()

WEBHOOK_SECRET = 'test_webhook_secret'

def make_webhook_payload(check_id: str, result: str) -> dict:
    return {
        'payload': {
            'resource_type': 'check',
            'action': 'check.completed',
            'object': {
                'id': check_id,
                'status': 'complete',
                'result': result,
                'href': f'https://api.onfido.com/v3.6/checks/{check_id}',
            },
        }
    }

def test_webhook_clear_result_approves_user(client, db_session):
    # Arrange: create a pending KYC record
    db_session.execute("INSERT INTO kyc_checks (check_id, user_id, status) VALUES ('chk_001', 'usr_001', 'pending')")

    payload = json.dumps(make_webhook_payload('chk_001', 'clear')).encode()
    signature = sign_payload(payload, WEBHOOK_SECRET)

    response = client.post(
        '/webhooks/onfido',
        data=payload,
        content_type='application/json',
        headers={'X-SHA2-Signature': signature},
    )

    assert response.status_code == 200
    kyc = db_session.execute("SELECT status FROM kyc_checks WHERE check_id = 'chk_001'").fetchone()
    assert kyc.status == 'approved'

def test_webhook_rejects_invalid_signature(client):
    payload = json.dumps(make_webhook_payload('chk_002', 'clear')).encode()
    response = client.post(
        '/webhooks/onfido',
        data=payload,
        content_type='application/json',
        headers={'X-SHA2-Signature': 'invalid_signature'},
    )
    assert response.status_code == 401

def test_webhook_idempotent_on_duplicate_delivery(client, db_session):
    db_session.execute("INSERT INTO kyc_checks (check_id, user_id, status) VALUES ('chk_003', 'usr_003', 'pending')")
    payload = json.dumps(make_webhook_payload('chk_003', 'clear')).encode()
    signature = sign_payload(payload, WEBHOOK_SECRET)

    # Deliver twice — simulates provider retry
    client.post('/webhooks/onfido', data=payload, content_type='application/json', headers={'X-SHA2-Signature': signature})
    response = client.post('/webhooks/onfido', data=payload, content_type='application/json', headers={'X-SHA2-Signature': signature})

    assert response.status_code == 200  # idempotent, not an error
    rows = db_session.execute("SELECT COUNT(*) FROM kyc_events WHERE check_id = 'chk_003'").fetchone()
    assert rows[0] == 1  # only one event recorded

Running Against Real Sandboxes

Reserve real sandbox API calls for a dedicated integration test suite that runs less frequently (nightly or pre-release, not on every PR):

// jest.config.js
module.exports = {
  projects: [
    {
      displayName: 'unit',
      testMatch: ['**/*.test.js'],
      testPathIgnorePatterns: ['integration'],
    },
    {
      displayName: 'integration',
      testMatch: ['**/integration/**/*.test.js'],
      testEnvironment: 'node',
      // Requires ONFIDO_API_KEY, ONFIDO_SANDBOX=true in env
    },
  ],
};

When running integration tests, use each vendor's official test documents and test API keys. Never use production keys in tests, and always check vendor documentation for sandbox-specific behaviors — Onfido's sandbox, for example, returns a fixed set of outcomes based on document type rather than the actual image content.


Summary Checklist

Before shipping a KYC integration, your test suite should cover:

  • Happy path: document accepted, user verified, features unlocked
  • Consider result: user blocked, manual review queue populated
  • Expired document: rejected with correct error code
  • Name mismatch: rejected, not silently approved
  • Image quality failure: blurry/glare/cropped rejected at quality check layer
  • Liveness failure: selfie match below threshold → declined
  • Webhook signature validation: invalid signature returns 401
  • Webhook idempotency: duplicate delivery does not double-process
  • Retry exhaustion: correct state after N failed attempts
  • Selfie-to-document mismatch: low confidence score results in manual review
  • All vendor error codes your code handles (including undocumented 5xx scenarios)
  • Race condition: webhook arrives before poll completes

Identity verification bugs are not just embarrassing — they are either security holes (too permissive) or user experience disasters (rejecting real users). Test every path.

Read more

Start now free