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:
- Real documents are sensitive. You can't store real passport scans in a test fixture repo.
- Third-party APIs are expensive. Onfido charges per check. Jumio charges per verification. You cannot run these on every CI build.
- Results are probabilistic. A "clear" result from an AI-based document check means the model was confident enough — not that it was definitely correct.
- 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'}}), 200Layer 2: Testing Document Verification Logic
Document verification typically involves:
- Image quality checks (blur, glare, crop)
- Document authenticity checks (MRZ validation, security features)
- Data extraction (name, DOB, expiry)
- 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 recordedRunning 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.