Web Capture Flow

The web capture flow is Verifa’s hosted verification experience. You create a session, redirect the user to the capture URL, and Verifa handles document scanning, selfie collection, liveness detection, and consent collection.

How it works

Your Server                    Verifa                         User
    │                            │                              │
    │  POST /api/v1/sessions     │                              │
    │───────────────────────────▶│                              │
    │  { capture_url }           │                              │
    │◀───────────────────────────│                              │
    │                            │                              │
    │  redirect to capture_url   │                              │
    │─────────────────────────────────────────────────────────▶│
    │                            │     consent + documents      │
    │                            │◀─────────────────────────────│
    │                            │     selfie + liveness        │
    │                            │◀─────────────────────────────│
    │                            │                              │
    │                            │  redirect to redirect_url    │
    │                            │─────────────────────────────▶│
    │                            │                              │
    │  webhook: session.approved │                              │
    │◀───────────────────────────│                              │

Step 1: Create a session

$
curl -X POST https://api.withverifa.com/api/v1/sessions \
>
  -H "X-API-Key: vk_live_your_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "external_ref": "user_abc123",
>
    "country": "US",
>
    "redirect_url": "https://your-app.com/verify/complete"
>
  }'

1
{
2
  "id": "session_abc123",
3
  "status": "pending",
4
  "capture_url": "https://app.withverifa.com/verify/tok_abc123...",
5
  "qr_code_data_url": "data:image/png;base64,...",
6
  "is_sandbox": false,
7
  "created_at": "2026-02-01T12:00:00Z",
8
  "expires_at": "2026-02-01T12:20:00Z"
9
}

Key parameters

Step 2: Send the user to capture

Option A: Full-page redirect

The simplest approach. Redirect the user to the capture_url:

1
// After creating a session on your server
2
window.location.href = session.capture_url;

After the user completes the flow, they are redirected to your redirect_url with query parameters:

https://your-app.com/verify/complete?session_id=session_abc123&status=completed

Option B: Iframe embed

Embed the capture flow in your page:

1
<iframe
2
  id="verifa-capture"
3
  src="https://app.withverifa.com/verify/tok_abc123..."
4
  allow="camera; microphone"
5
  style="width: 100%; height: 700px; border: none;"
6
></iframe>

Listen for completion via postMessage:

1
window.addEventListener("message", (event) => {
2
  if (event.origin !== "https://app.withverifa.com") return;
3
4
  const { type, session_id, status } = event.data;
5
6
  if (type === "verifa:complete") {
7
    console.log(`Session ${session_id} completed with status: ${status}`);
8
    // Remove iframe and show success state
9
  }
10
11
  if (type === "verifa:error") {
12
    console.error("Capture error:", event.data.error);
13
  }
14
});

Option C: QR code

Display the qr_code_data_url so mobile users can scan and complete verification on their phone:

1
<img src="${session.qr_code_data_url}" alt="Scan to verify" />
2
<p>Scan with your phone camera to complete verification</p>

This is useful for desktop-first flows where the user’s phone has a better camera.

Step 3: Capture flow screens

The capture flow guides the user through these screens (order depends on your workflow’s data_requirements):

1. Consent

Biometric processing consent. Records timestamp, IP address, and consent version. Required before any data collection.

2. Document type selection

The user selects their document type:

• Passport
• Driver’s license
• National ID card
• Residence permit

Available types are scoped by the country parameter.

3. Document upload

Front side (required) and back side (if applicable). The capture UI provides:

• Real-time camera viewfinder with alignment guides
• Auto-capture when a document is detected
• Manual photo option as fallback
• Image quality feedback (blur, glare, resolution)

Documents are encrypted with AES-256-GCM immediately on upload. Maximum file size: 10 MB.

4. Selfie

Live selfie capture with alignment guide. The selfie is compared against the ID photo for face matching.

5. Liveness challenge

Three randomized challenges from: blink, smile, turn left, turn right, look up, nod, open mouth. Challenges are cryptographically bound to the session via a server-generated nonce to prevent replay attacks.

6. Additional data (optional)

If your workflow requires it:

• Email and phone — For risk scoring and OTP verification
• Address — For address validation checks
• Proof of address — Upload utility bill or bank statement
• SSN — For US-specific checks

Step 4: Handle the result

Via webhook (recommended)

Configure a webhook endpoint to receive real-time notifications:

1
{
2
  "event": "session.approved",
3
  "data": {
4
    "session_id": "session_abc123",
5
    "external_ref": "user_abc123",
6
    "status": "approved",
7
    "is_sandbox": false
8
  },
9
  "created_at": "2026-02-01T12:05:00Z"
10
}

See Webhooks for setup and signature verification.

Via polling

Poll the session status until it reaches a terminal state:

$
curl https://api.withverifa.com/api/v1/sessions/session_abc123 \
>
  -H "X-API-Key: vk_live_your_key_here"

Once status is completed, fetch the result:

$
curl https://api.withverifa.com/api/v1/sessions/session_abc123/result \
>
  -H "X-API-Key: vk_live_your_key_here"

Capture token expiration

The capture URL token expires after 20 minutes by default. If the user doesn’t complete the flow in time, the session status changes to expired.

To re-issue a token for an expired session:

$
curl -X POST https://api.withverifa.com/api/v1/sessions/session_abc123/resume \
>
  -H "X-API-Key: vk_live_your_key_here"

This returns a new capture_url with a fresh token. Previously uploaded documents are preserved.

Fraud signal collection

The capture flow automatically collects 150+ fraud signals in the background:

• Behavioral — Completion time, hesitation patterns, copy-paste detection, keystroke dynamics, mouse/touch patterns
• Device — Browser fingerprint, bot detection, virtual camera detection, WebGL analysis, memory constraints
• Network — IP consistency, user-agent tracking, timezone validation
• Document — EXIF metadata analysis, blur/glare detection, screen photo detection, forensic analysis

These signals feed into the risk_assessment check during workflow execution. You don’t need to collect or submit them — the capture flow handles everything.

Theming

Customize the capture flow appearance in the Verifa dashboard under Settings > Organization (Theming section):

• Primary and accent colors
• Logo
• Font family
• Button styles
• Background colors

Error handling

If the capture flow encounters an error, the user sees an error screen with a retry option. Common errors:

Related

• Sessions — Full session lifecycle and API
• Choosing an Integration Method — Compare with other options
• Fraud Signals — What signals are collected during capture
• Testing — Test the capture flow in sandbox