Document Acquisition

Captures a document image from the user for identity verification

A journey is a sequence of steps that are executed when it's invoked by a client application (known as the "client"). Some steps require involvement from the client, such as to collect user input. Other steps, like validating a token, are executed in the backend by the Mosaic journey engine alone.

When invoked, the journey begins executing the steps while the client waits for further instructions. When a journey reaches a client-facing step, the journey asks the client for the required input and then waits for the client to respond. The client presents their own UI if user interaction is required, and returns input to the journey. The journey then proceeds in a similar manner until it's completed.

This client-facing step is used to obtain a document image from the user and pass it to Mosaic Identity Verification for further processing. This step captures images of a government-issued identity document (such as a driver's license, passport, or national ID card) which can then be used for document validation and identity verification.

After triggering this step, Mosaic creates the Identity Verification session. The client uses the Identity Verification SDK to proceed with document image acquisition. On web apps, you invoke the Identity Verification SDK from the client. On mobile apps, the handoff is handled implicitly by the Orchestration SDK.

If the step is successful, the journey stores the document data in the output variable and proceeds to the next step, typically the Selfie Acquisition or IDV Recommendation.

If it fails (e.g., user didn't upload the picture), the journey will proceed to the failure branch.

Suppose your app requires a user to capture an identity document and submit it for further processing and verification.

Register an ITSUIHandler after you initialize the Orchestration SDK and before you start the journey. The SDK intercepts this step, runs document capture, and submits the result. You don't need to handle journeyStepId in your journey switch or start the Identity Verification SDK yourself.

Implement onBefore and onAfter to present your own UI around the SDK capture screens, then call proceed() to continue.

The handler interface also requires a selfie acquisition handler. If the journey doesn't include Selfie Acquisition, leave that handler as a pass-through that calls proceed().

// Hook into document and selfie acquisition steps.
class MyUIHandler(private val activity: FragmentActivity) : ITSUIHandler {

    override fun provideDocumentAcquisitionHandler(): TSIDVStepHandler = TSIDVStepHandler().apply {
        onBefore = { context ->
            // Show your own UI before the SDK document capture starts, then continue.
            context.proceed()
        }
        onAfter = { context ->
            // Show your own UI after document acquisition completes, then continue.
            context.proceed()
        }
    }

    override fun provideSelfieAcquisitionHandler(): TSIDVStepHandler = TSIDVStepHandler().apply {
        // Required by ITSUIHandler. Call proceed() if this journey doesn't capture a selfie.
        onBefore = { context -> context.proceed() }
        onAfter = { context -> context.proceed() }
    }
}

// Register after TSIdo.initializeSDK(...) and before TSIdo.startJourney(...).
TSIdo.setUIHandler(MyUIHandler(activity))

TSIdo.startJourney(journeyId, TSIdoStartJourneyOptions(...), listener)

When executed, this step sends a callback to the client. The journeyStepId is set to document acquisition (transmit_platform_document_acquisition). The response data includes:

• acquisition_id (required): ID used to start document capture
• start_token (optional): used to start an Identity Verification session if one isn't already active

If start_token is present, start the Identity Verification session, then call captureDocument() with the acquisition_id. After capture completes, submit an empty client response. Handle capture errors in the app (for example, inform the user or retry).

Initialize the Orchestration and Identity Verification modules before starting the journey. Identity Verification also requires the Fraud Prevention module. Configure all modules for the same region.

import { ido, idv, ClientResponseOptionType, IdoJourneyActionType } from '@transmitsecurity/platform-web-sdk';

async function handleJourneyResponse(idoResponse) {
  if (idoResponse.journeyStepId === IdoJourneyActionType.DocumentAcquisition) {
    await handleDocumentAcquisition(idoResponse);
  }
}

async function handleDocumentAcquisition(idoResponse) {
  const startToken = idoResponse.data?.start_token;
  const acquisitionId = idoResponse.data?.acquisition_id;

  // Start an Identity Verification session when the journey provides a start token
  if (startToken !== undefined) {
    await idv.start(startToken);
  }

  await idv.captureDocument({ acquisitionId });

  // After acquiring the document, the client response does not need to include any data
  // If SDK was loaded via script tag, invoke functions inside 'window.tsPlatform'
  return ido.submitClientResponse(ClientResponseOptionType.ClientInput);
}