Skip to main content

@zyphe-sdk/browser

Install the package:

pnpm add @zyphe-sdk/browser

Embedding the Zyphe Verification Iframe​

Use the startVerificationSession function to embed a Zyphe verification flow in your web app:

import { startVerificationSession } from '@zyphe-sdk/browser'

const container = document.getElementById('your-container-id')

const flowParams = {
  // Provide at least one identity field: email or a credential.
  email: 'user@example.com',
  credentials: [
    { type: 'EXTERNAL_ID', externalId: 'user_123' },
    { type: 'WALLET', address: '0x123...', chain: 'ETHEREUM' },
  ],
  flowId: 'your-flow-id',
  isSandbox: true, // or false for production
  customData: {/* optional custom data */}, // Optional: pass any extra data needed for your flow
}

const opts = {
  apiKey: 'your-api-key',
  // ...other SDK options
}

const result = await startVerificationSession({
  containerElement: container,
  flowParams,
  opts,
  eventHandlers: {
    onSuccess: (message) => {
      // Handle success
      console.log('Verification completed successfully')
      console.log('Completed step:', message.flowStep)
      console.log('Verification request session:', message.vrSession)
    },
    onFailure: (message) => {
      // Handle failure
      console.log('Verification failed')
      console.log('Failure details:', message.error)
    },
  },
})

if (result.error) {
  // Handle error (e.g., show a message to the user)
  console.error('Failed to start verification session:', result.error)
} else {
  // Session created successfully, iframe embedded
  console.log('Verification session started successfully')
}

Key Features​

  • Non-throwing API: The function returns a Result object: { error, data }. If session creation fails, error will be set and no iframe will be embedded.
  • Automatic iframe management: Creates and appends an iframe to the specified container with proper styling and permissions.
  • Event handling: Listen for success and failure events from the verification flow, including the completed flow, flow step, and verification request session context.
  • Camera permissions: The iframe is automatically configured with camera permissions for document and identity verification.
  • Identity credentials: Start a session with email, an EXTERNAL_ID credential, a WALLET credential, or any combination. At least one is required.
Email aliases not supported in production

The email field in flowParams does not accept email aliases (e.g. user+tag@example.com) in production environments. Use a plain email address without +alias suffixes when isSandbox is false.

API Reference​

startVerificationSession({ containerElement, flowParams, opts, eventHandlers })​

Creates a verification session and embeds the Zyphe iframe in the specified container.

Parameters​

  • containerElement: HTMLElement - The DOM element to append the iframe to
  • flowParams: InitializeZypheFlowParams - The parameters for the verification flow
    • email?: string - User's email address. Required only when credentials does not include an external ID or wallet.
    • credentials?: VerificationIdentifierCredential[] - User credentials. Include { type: 'EXTERNAL_ID', externalId: 'user_123' } and/or { type: 'WALLET', address: '0x123...', chain: 'ETHEREUM' }.
    • flowId: string - The ID of the verification flow
    • flowStepId?: string - Optional. If omitted, the next incomplete step is selected automatically.
    • isSandbox: boolean - Whether to use sandbox or production environment
    • customData?: any - Optional custom data to pass to the flow
  • opts: SDKOptions - SDK configuration options (e.g., { apiKey }). Optional theming overrides are also accepted. See Theming for the full list.
  • eventHandlers?: { onSuccess?, onFailure? } - Optional event handlers
    • onSuccess?: (message: ZypheVerificationSuccessMessage) => void - Called when verification completes successfully
    • onFailure?: (message: ZypheVerificationFailureMessage) => void - Called when verification fails

Verification event payloads​

The browser SDK listens to the iframe postMessage events emitted by the Zyphe verification flow. Both success and failure handlers receive the full event payload.

type ZypheVerificationSuccessMessage = {
  type: 'zyphe-verification-success'
  flow: Flow
  flowStep: FlowStep
  vrSession: {
    customData?: VerificationRequest['customData']
    email?: string
    verificationRequestId?: string
  }
}

type ZypheVerificationFailureMessage = {
  type: 'zyphe-verification-failure'
  flow: Flow
  flowStep: FlowStep
  vrSession: {
    customData?: VerificationRequest['customData']
    email?: string
    verificationRequestId?: string
  }
  error?: string | { code?: string; message?: string }
}
  • flow: The flow where the verification event happened.
  • flowStep: The flow step that completed or failed.
  • vrSession: Verification request session context, including verificationRequestId, email, and customData.
  • error: Failure details. This field is only present on zyphe-verification-failure events.

Returns​

Promise<{ error?: any, data?: any }> - A Result object

  • If error is present, session creation failed and no iframe is embedded
  • If data is present, session was created and iframe is embedded

Example​

const result = await startVerificationSession({
  containerElement: document.getElementById('verification-container'),
  flowParams: {
    email: 'user@example.com',
    credentials: [{ type: 'EXTERNAL_ID', externalId: 'user_789' }],
    flowId: 'flow_123',
    isSandbox: true,
    customData: { userId: 'user_789' },
  },
  opts: { apiKey: 'your-api-key' },
  eventHandlers: {
    onSuccess: (message) => {
      console.log('Verification successful', message.flowStep.type)
    },
    onFailure: (message) => {
      console.log('Verification failed', message.error)
    },
  },
})

Browser Compatibility​

This SDK requires a modern browser with support for:

  • ES6+ features
  • Web Crypto API (for future webhook signature verification)
  • Iframe elements