Configuration

Comprehensive configuration options for the VECU IDV Web SDK.

SDK Initialization

Configure the SDK instance using createVecuIDVSDK():

import { createVecuIDVSDK } from 'vec-idp-web-sdk';

const sdk = createVecuIDVSDK({
  // Required: Deployment environment
  deploymentStage: 'sandbox', // 'sandbox' | 'production'

  // Required: Authentication
  bearerToken: 'your-bearer-token',

  // Optional: API configuration
  apiUrl: 'http://localhost:8080', // For local mock server testing only (auto-detected from deploymentStage if not provided)
  timeout: 30000, // Request timeout in ms (default: 30000)
  maxRetries: 3, // Number of retry attempts (default: 3)

  // Optional: Debug and logging
  debug: true, // Enable debug mode (default: false)
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
});

Initialization Options

Verification Config Options

Properties available in the config object when calling startVerificationWithCustomer():

await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  referenceId: 'customer-12345',
  config: {
    qrCode: true, // Enable QR code for mobile handoff
    showSsnOnInitialForm: true, // Show SSN field in form
    showEmail: true, // Show email field in address confirmation
    showPhone: true, // Show phone field in address confirmation
    allowPhoneEdit: false, // Allow user to edit pre-populated phone
    hideEmailDisplay: false, // Hide email from form (still sent to API)
    allowEmailOverride: false, // Show editable Personal Email above readonly Company Email
    tamperingBehavior: 'warn', // 'warn' | 'block'
  },
});

qrCode

await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  config: {
    qrCode: true, // Users can scan QR code for mobile handoff
  },
});

showSsnOnInitialForm

// Hide SSN field for privacy compliance
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  config: {
    showSsnOnInitialForm: false, // Field hidden & excluded from API
  },
});

showEmail / showPhone

allowPhoneEdit

// Allow users to edit their phone number
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  config: {
    allowPhoneEdit: true, // Phone field is editable
  },
});

hideEmailDisplay

// Hide email from form display (still submitted to API)
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  config: {
    hideEmailDisplay: true, // Email hidden from UI, still sent to backend
  },
});

allowEmailOverride

// Opt in to the dual Company / Personal Email layout
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    email: 'user@acme.com', // Company email known at session start
    /* ... */
  },
  config: {
    allowEmailOverride: true,
  },
});

tamperingBehavior

• 'warn' (default): Allows form submission but emits address:field_tampering_detected events for audit logging
• 'block': Prevents form submission and displays error messages, emits address:field_tampering_blocked events

// Block mode - prevents submission when tampering detected
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  config: {
    tamperingBehavior: 'block',
  },
});

// Listen for tampering events
sdk.on(SdkEvent.ADDRESS_FIELD_TAMPERING_DETECTED, event => {
  console.warn('Field modified:', event.data);
  // event.data: { field, expectedValue, receivedValue }
});

Display Modes

The SDK supports two display modes:

Embedded Mode

The verification UI renders inside the container element, inheriting its dimensions.

// Container needs dimensions
<div id="container" style={{ minHeight: '600px', width: '100%' }} />

await sdk.startVerificationWithCustomer('#container', {
  customerInfo: { /* ... */ },
  mode: 'embedded'  // Default
});

Modal Mode

The verification UI appears in a centered modal overlay.

// Container used as attachment point only
<div id="container" />

await sdk.startVerificationWithCustomer('#container', {
  customerInfo: { /* ... */ },
  mode: 'modal'
});

Updating Configuration

Update SDK configuration after initialization using updateConfig():

// CORRECT - Await the config update
await sdk.updateConfig({
  deploymentStage: 'production',
  bearerToken: 'your-new-token'
});

// Now safe to start verification
await sdk.startVerificationWithCustomer(...);

// WRONG - Missing await causes race condition!
sdk.updateConfig({  // Missing await!
  deploymentStage: 'production',
  bearerToken: 'your-new-token'
});

await sdk.startVerificationWithCustomer(...);  // Will use OLD token!

Environment Variables

For React applications:

const sdk = createVecuIDVSDK({
  deploymentStage:
    process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
  bearerToken: process.env.REACT_APP_BEARER_TOKEN,
  debug: process.env.NODE_ENV === 'development',
});

For Next.js applications:

const sdk = createVecuIDVSDK({
  deploymentStage:
    process.env.NODE_ENV === 'production' ? 'production' : 'sandbox',
  bearerToken: process.env.NEXT_PUBLIC_BEARER_TOKEN,
  debug: process.env.NODE_ENV === 'development',
});

For Vue/Vite applications:

const sdk = createVecuIDVSDK({
  deploymentStage: import.meta.env.PROD ? 'production' : 'sandbox',
  bearerToken: import.meta.env.VITE_BEARER_TOKEN,
  debug: import.meta.env.DEV,
});

Provider Configuration

The identity verification provider is managed entirely server-side. The SDK automatically detects and adapts to the active provider — no client-side configuration is required.

Next Steps

• API Reference - Explore all available methods
• Events - Handle verification events
• Frameworks - Framework-specific guides