Integrate Document Capture on web

Use the Youverify Web SDK to let users capture an identity document from inside your web application. The SDK opens a modal, guides the user through capturing the document, and returns the extracted details to your page.

Before you start

You need your Public Merchant Key. You can find it in the API / Webhook section of your Youverify dashboard. It is safe to use in client-side code.

Document Capture on web is initialized with your Public Merchant Key. You don’t need to generate a session ID on your server for this flow. Keep your secret API key on your server and never put it in a web page.

Installation

npm
yarn

npm install youverify-web-sdk

yarn add youverify-web-sdk

Integration steps

Create the Document Capture module

Pass your options to YouverifySDK.documentCapture:

const documentCaptureModule = new YouverifySDK.documentCapture({
  publicMerchantKey: 'YOUR_PUBLIC_MERCHANT_KEY',
  sandboxEnvironment: true, // set to false in production

  personalInformation: {
    firstName: 'John',
  },

  // Optional: customize the greeting, button text and colours
  appearance: {
    greeting: 'We will need to capture your document. It will only take a moment.',
    actionText: 'Capture Document',
    buttonBackgroundColor: '#46B2C8',
    buttonTextColor: '#ffffff',
    primaryColor: '#46B2C8',
  },

  // Optional: restrict the countries and document types
  countries: [
    {
      countryCode: 'ng',
      idTypes: ['passport', 'Residence Permit', 'Driving License', 'NIN'],
    },
  ],

  onSuccess: (data) => {
    // The user captured the document and you received the result
  },
  onFailure: (error) => {
    // The result could not be retrieved
  },
  onClose: () => {
    // The user closed the modal
  },
});

Initialize the module

Call initialize() once. It throws if the options are invalid, so wrap it in a try block.

try {
  documentCaptureModule.initialize();
} catch (error) {
  // Handle the validation error
}

Start the capture flow

Call start() when your user is ready, for example on a button click. This opens the modal.

documentCaptureModule.start();

Options

string

required

Your Public Merchant Key from the API / Webhook section of your dashboard.

boolean

default:"false"

Set to true to run in sandbox mode while you develop and test. Set to false for production.

boolean

default:"false"

Set to true to hide the option to capture the document with a secondary device.

object

User attributes used to personalize the experience.

Show properties

string

The user’s first name.

object

Customize the greeting text, button text and colours. All fields are optional.

Show properties

string

The text shown to the user before capture starts.

string

The label of the button that starts the capture.

string

Button background colour as a hex value, for example #46B2C8.

string

Button text colour as a hex value, for example #ffffff.

string

The main accent colour of the modal.

array

Limit the capture to specific countries and document types. Each item is an object. All fields are optional.

Show properties

string

The country the document should be captured for, for example ng or CA.

string[]

The document types to offer in that country, for example ["passport", "Driving License"].

string[]

The province or state within the country. Leave it out if the country has no provinces.

object

Any other information you want sent to your webhook URL. Use your own keys.

(data) => void

Called when document capture has a result. See Success result.

(error) => void

Called when the result could not be retrieved. Receives an error object.

() => void

Called when the modal is closed.

To see which countries, provinces and document types are supported, see Country and product coverage.

Success result

When capture succeeds, onSuccess receives an object like this:

{
  documentNumber: 'xyz',
  firstName: 'John',
  lastName: 'Doe',
  fullName: 'John Doe',
  dateOfBirth: '29-01-2022',
  dateOfExpiry: '29-01-2022',
  gender: 'M',
  rawMRZString: '*****...',
  fullDocumentFrontImage: '', // base64 image of the document's front
  fullDocumentBackImage: '',  // base64 image of the document's back
  fullDocumentImage: ''       // base64 image of the front, when there is no back to capture
}

string

Base64 image of the front of the document.

string

Base64 image of the back of the document.

string

Base64 image of the front of the document. Present when the document has no back to capture.

The result contains personal data and document images. Send it to your backend over HTTPS and don’t write it to logs or store it in the browser.

If you don’t pass an onSuccess callback, nothing happens when capture succeeds. You can close the SDK modal from your own code with setShowModal. It takes a Boolean and returns nothing.

Method	Parameters	Returns	Description
`setShowModal`	Boolean	None	Closes the SDK modal from code.

Use it in a mobile app

There is no native mobile SDK for Document Capture yet. To offer it in an Android or iOS app, you can wrap this web integration in a WebView. See Use Document Capture in a mobile app.

Get Started

Platform Concepts

Implementation Guides

Webhooks & Events

SDKs

Resources

Integrate Document Capture on web

Before you start

Installation

Integration steps

Options

Success result

Use it in a mobile app

​Before you start

​Installation

​Integration steps

​Options

​Success result

​Close the modal from code

​Use it in a mobile app

Before you start

Installation

Integration steps

Options

Success result

Close the modal from code

Use it in a mobile app