Skip to content

Latest commit

 

History

History
593 lines (423 loc) · 27.2 KB

netverify-web-v4-migration.md

File metadata and controls

593 lines (423 loc) · 27.2 KB

Jumio

Netverify Web v4 Migration Guide

Welcome to the new Netverify Web client!

This document is intended as a reference manual for customers migrating from Netverify Web v3 to Netverify Web v4. (Which version of the Netverify Web client am I using?)

It provides an overview of the significant changes in the new client and describes the adjustments that will be need to be made to your implementation to use the new version.


⚠️ Netverify Web v3 is officially being deprecated and will not be supported after December 18, 2018.

Revision history

Information about changes to features and improvements documented in each release is available in our Revision history.

Table of contents


Initiating a Netverify transaction

The Netverify Web v4 client uses a single API endpoint for all Netverify transactions.

Call the RESTful API POST endpoint /initiate with the updated JSON parameters as described below to create a transaction for each user. You will receive a JSON object in the response containing a timestamp, Jumio transaction reference (formerly scan reference), and a URL you can now use to present Netverify to your users in any way you like — embedded in an iFrame, as a link on your website, or shared

Netverify Web (Embedded) v3

HTTP Request Method: POST
REST URL (US): https://netverify.com/api/netverify/v2/initiateNetverify
REST URL (EU): https://lon.netverify.com/api/netverify/v2/initiateNetverify

Netverify Web (Redirect) v3

HTTP Request Method: POST
REST URL (US): https://netverify.com/api/netverify/v2/initiateNetverifyRedirect
REST URL (EU): https://lon.netverify.com/api/netverify/v2/initiateNetverifyRedirect

NVW4 (to initiate all transactions)

HTTP Request Method: POST
REST URL (US): https://netverify.com/api/v4/initiate
REST URL (EU): https://lon.netverify.com/api/v4/initiate


Authentication and encryption

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

⚠️ Never share your API token, API secret, or Basic Auth credentials with anyone — not even Jumio Support.

Request headers

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Request body

With this version of the Netverify Web client, we have begun the process of improving consistency across all of our APIs. This will be done gradually, to make the transition as smooth as possible for our existing customers.

Some of the initiate API request fields have been retained, but have new names. Some previously mandatory fields are now optional, and some optional fields are now mandatory. We have also deprecated some fields and added a few new ones. Our changes are described below.

ℹ️ Values set in your API request will override the corresponding settings configured in the Customer Portal.

Fields retained from v3 to v4 (with changes where applicable)

Changes to the fields in the initiate API request are listed in the tables below.

Required fields appear in bold type.

NVW3 embedded
NVW3 redirect		 NVW4 Type Max. length Changes
merchantIdScanReference1 customerInternalReference1 string 100 Field has been renamed.
customerId1
(optional for embedded)		 userReference1 string 100 Field has been renamed and is mandatory.
merchantReportingCriteria reportingCriteria string 100 Field has been renamed.
successUrl2
(optional for redirect)		 successUrl2 string 255 Previously required for embedded, if not set in the Customer Portal. Now optional.
Overrides Success URL in the Customer Portal.
errorUrl2
(optional for redirect)		 errorUrl2 string 255 Previously required for embedded, if not set in the Customer Portal. Now optional.
Overrides Error URL in the Customer Portal.
callbackUrl2 callbackUrl2 string 255 No change.
Overrides Callback URL in the Customer Portal.
locale locale string 5 Hyphen replaces underscore in format for extended locale (language + country).
Overrides Default locale in the Customer Portal.
See supported locale values.
authorizationTokenLifetime tokenLifetimeInMinutes number Max value: 86400 Previously in seconds, now in minutes. (minimum: 5, maximum: 86400)
Overrides Authorization token lifetime in the Customer Portal.

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.
2 See URL constraints for Callback, Error, and Success URLs.


Supported locale values

Hyphenated combination of ISO 639-1:2002 alpha-2 language code plus ISO 3166-1 alpha-2 country (where applicable).

Value Locale
bg Bulgarian
cs Czech
da Danish
de German
el Greek
en American English (default)
en-GB British English
es Spanish
es-MX Mexican Spanish
et Estonian
fi Finnish
fr French
hu Hungarian
it Italian
ja Japanese
ko Korean
lt Lithuanian
nl Dutch
no Norwegian
pl Polish
pt Portuguese
pt-BR Brazilian Portuguese
ro Romanian
ru Russian
sk Slovak
sv Swedish
tr Turkish
vl Vietnamese
zh-CN Simplified Chinese
zh-HK Traditional Chinese

New optional fields

Netverify Web v4 introduces the concept of acquisition workflows and presets to allow you to customize every transaction based on your needs for each user.

The workflowId parameter lets you optionally specify a combination of verification and capture method options for each transaction. If you choose not to use this field, Identity Verification will be performed on all transactions if it is enabled in your account settings, and the Capture method you specify in the Customer Portal will apply.

The presets parameter lets you optionally specify certain information to enhance the user journey. You can use the ID Verification preset to set the country and document type, bypassing the selection screen in the user journey. You can also specify an Identity Verification preset that allows you to set a custom Liveness Detection phrase for the transaction. You may use the ID Verification preset separately, the Identity Verification preset separately, both presets together, or skip them entirely — but you must specify all required values for the preset if you choose to use it.


NVW4 Parameter Type Max. length Description
workflowId integer 3 Applies this acquisition workflow to the transaction.
Overrides Capture method in the Customer Portal.
See supported workflowId values.
presets1 JSON - Preset options to enhance the user journey.
See supported presets values.

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.


Supported workflowId values

⚠️ Identity Verification must be enabled for your account to use an ID + Identity workflowId.
Value Verification type Capture method
100 ID only camera + upload
101 ID only camera only
102 ID only upload only
200 ID + Identity camera + upload
201 ID + Identity camera only
202 ID + Identity upload only

Supported presets values

It is possible to specify presets for ID Verification, for Identity Verification, for both together, or for neither. For each preset you use, all values must be passed together as a JSON array (see Sample request) for the request to be valid.

ID Verification: preset country and document type

Preset the country and document type to bypass the selection screen.

Required items appear in bold type.

Name Type Max. length Description
index integer 1 must be set to 1
country string 3 Possible values:
• ISO 3166-1 alpha-3 country code
• XKX (Kosovo)
type string 15 Possible values:
• PASSPORT
• DRIVING_LICENSE
• ID_CARD

Identity Verification: preset Liveness Detection phrase

Preset a custom Liveness Detection phrase for the transaction.

⚠️ Identity Verification and Liveness Detection must be enabled for your account to use this preset.

Required items appear in bold type.

Name Type Max. length Description
index integer 1 must be set to 2
phrase1 string 30 Possible values:
• alpha-numeric Latin characters (upper or lower case) and spaces

1 Values must not contain Personally Identifiable Information (PII) or other sensitive data such as email addresses.


Deprecated properties

Property Notes
clientIp This property has been removed.
firstName This property has been removed.
lastName This property has been removed.
country This property has been removed.
usState This property has been removed.
expiry This property has been removed.
number This property has been removed.
dob This property has been removed.
idType This property has been removed.
personalNumber This property has been removed.
enabledFields This property has been removed.
Mandatory fields and optional fields enabled in the Customer Portal will be extracted by default.
Address will be extracted if it is enabled for your account, and extraction is supported for the country/document type. See supported documents for address extraction.
Identity Verification can now be requested on a per-transaction basis using workflowId.
captureMethod This property has been replaced by workflowId.
presetCountry This property has been replaced by presets.
presetIdType This property has been replaced by presets.

Supported documents for address extraction

Country ID card Driving license Passport Callback format
Australia No Yes No US
Canada No Yes No US
France Yes Yes Yes Raw
Germany Yes No No EU
Ireland No Yes No Raw
Mexico Yes No No US
Romania Yes No No Raw
Singapore Yes No No Raw
Spain Yes No No EU
United Kingdom No Yes No Raw
United States No Yes No US

Response

Unsuccessful initiate requests will return the relevant HTTP status code and information about the cause of the error.

Successful requests will return HTTP status code 200 OK along with the NVW4 parameters listed below.

Fields retained from v3 to v4 (with changes where applicable)

NVW3 embedded
NVW3 redirect		 NVW4 Type Max. length Changes
timestamp timestamp String 24 No change.
Timestamp (UTC) of the response.
Format: YYYY-MM-DDThh:mm:ss.SSSZ
clientRedirectUrl
(redirect only)		 redirectUrl String 255 Field has been renamed.
This URL is now used to display the Netverify Web client regardless of implementation.
jumioIdScanReference transactionReference String 36 Field has been renamed.
Jumio reference number for the transaction.

Deprecated fields

Parameter Notes
authorizationToken This field has been removed.

Examples

Sample NVW4 request

POST https://netverify.com/api/v4/initiate/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 1234
User-Agent: Example Corp SampleApp/1.0.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
  "customerInternalReference" : "transaction_1234",
  "userReference" : "user_1234",
  "successUrl" : "https://www.yourcompany.com/success",
  "errorUrl" : "https://www.yourcompany.com/error",
  "callbackUrl" : "https://www.yourcompany.com/callback",
  "reportingCriteria" : "myReport1234",
  "workflowId" : 200,
  "presets" :
    [
      {
        "index"   : 1,
        "country" : "AUT",
        "type"    : "PASSPORT"
      },{      
        "index"   : 2,
        "phrase" : "MY CUSTOM PHRASE"     
      }
    ],
  "locale" : "en-GB"
}
⚠️ Sample requests cannot be run as-is. Replace example data with your own parameter values.

Sample NVW4 response

{
  "timestamp": "2018-07-03T08:23:12.494Z",
  "transactionReference": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "redirectUrl": "https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxx"
}

Configuring settings in the Customer Portal

In the Settings screen of the Customer Portal you can customize your settings and brand your Netverify page.
Save changes using your Customer Portal password to activate them.

ℹ️ Values set in your API request will override the corresponding settings configured in the Customer Portal.

Application settings — General

Callback, Error, and Success URLs

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Capture method

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Skip "Start ID verification" screen

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Authorization token lifetime

Specify the duration of time for which your redirectUrl will remain valid. Enter the value in minutes (minimum 5, maximum 86400). The default value is 30 minutes.


Application settings — Redirect

Domain name prefix

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Max attempts per user

This has been deprecated and will be removed.

Default locale

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Enable additional information field

This has been deprecated and will be removed.


Customize client

General (Colors)

No change from v3. See the new Netverify Web v4 Implementation Guide for further information.

Redirect (Images)

Add a Header image for each locale to brand your Netverify page.

Intro image has been deprecated and will be removed.

Add a Success image and Error image for each locale to be displayed on the Jumio default success and error pages when you do not specify your own successUrl and errorUrl.

Any locale which is not configured will first default to the root language (e.g. EN_GB to EN), then to your default configuration, and finally to the Jumio default.

All images must be formatted as JPG or PNG and must not exceed 5 MB.

Label for customer ID and Label for additional information have been deprecated and will be removed.


Displaying Netverify

To make things easier, we've simplified displaying the Netverify Web client.

The redirectUrl returned in the response to your initate API call, which loads your customized Netverify page, can be used in several ways:

  • within an iFrame on your web page
  • as a link on your web page
  • as a link shared securely with a user

Using Netverify in an iFrame

If you want to embed Netverify on a web page, there's no longer a need to run any scripts. Simply place the iFrame tag in your HTML code where you want the client to appear, and use the redirectUrl as the value of the src attribute. The allow="camera" attribute must be included to enable the camera for image capture in supported browsers.

Width and height

We recommend adhering to the responsive breaking points in the table below. The Netverify client will responsively fill the dimensions of your iFrame.

Size class Width Height
Large ≥ 900 px ≥ 710 px
Medium 640 px 660 px
Small 560 px 600 px
X-Small ≤ 480 px ≤ 535 px

Example HTML

<iframe src="https://yourcompany.netverify.com/web/v4/app?locale=en-GB&authorizationToken=xxxx
xxxxxxx" width="930" height="750" allow="camera"></iframe>

Optional iFrame logging

We've updated our optional iFrame logging feature to extend its functionality. We've added some new data objects, but the mechanism remains the same.

When the Netverify client is embedded in an iFrame1, it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g., by directing to a new page once the success event is received). Events include data that allows the containing page to identify which Netverify transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that took occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by the Netverify Web client in this notification is represented as JSON in the data string property of the listener method's event argument. Parsing this JSON string results in an object with the properties described below.

All data is encoded with UTF-8.

1 This functionality is not available for instances of Netverify running in a standalone window or tab.

event.data object

Required fields appear in bold type.

NVW3 NVW4 Type Description
authorizationToken authorizationToken string Authorization token, valid for a specified duration.
scanReference transactionReference string Jumio reference number for the transaction.
timestamp dateTime string UTC timestamp of the event in the browser.
Format: YYYY-MM-DDThh:mm:ss.SSSZ
customerInternalReference string Your internal reference for the transaction.
eventType integer Type of event that has occurred.
Possible values:
• 510 (application state-change)
payload JSON object Information specific to the event generated (see event.data.payload object)

event.data.payload object

This new object gives us the option to notify you when the Netverify Web client is loaded, and when the user journey ends with either a success or an error.

Required fields appear in bold type.

Property Type Description
value string Possible values:
• loaded (Netverify loaded in the user's browser.)
• success (Images were accepted for verification.)
• error (Verification could not be completed due to an error.)
metainfo JSON object Additional meta-information for error events.
(see event.data.payload.metainfo object)

event.data.payload.metainfo object

When the user journey ends with an error, this new object allows us to give you more information about what happened.

Required fields appear in bold type.

Property Type Description
code integer see errorCode values

Example iFrame logging code

function receiveMessage(event) {
	var data = window.JSON.parse(event.data);
	console.log('Netverify Web was loaded in an iframe.');
	console.log('auth token:', data.authorizationToken);
	console.log('transaction reference:', data.transactionReference);
	console.log('customer internal reference:', data.customerInternalReference);
	console.log('event type:', data.eventType);
	console.log('date-time:', data.dateTime);
	console.log('event value:', data.payload.value);
	console.log('event metainfo:', data.payload.metainfo);
}
window.addEventListener("message", receiveMessage, false);

After the user journey

At the end of the user journey, the user is directed to your successUrl if the images they submitted were accepted for processing. If no successUrl has been defined, the Jumio default success page will be displayed, including any custom success image you have specified in the Customer Portal.

If acceptable images are not provided after three attempts (see Reject reasons), the user is directed to your errorUrl. If no errorUrl has been defined, the Jumio default error page will be displayed, including any custom error image you have specified in the Customer Portal.

To display relevant information on your success or error page, you can use the following parameters which we append when redirecting to your successUrl or errorUrl as HTTP GET query string parameters1. It is also possible to set your successUrl and errorUrl to the same address, by using the query parameter transactionStatus.

NVW3 NVW4 Description
idScanStatus transactionStatus Possible values:
SUCCESS for successful submissions
ERROR for errors and failure after 3 attempts
merchantIdScanReference customerInternalReference Your internal reference for the transaction.
jumioIdScanReference transactionReference Jumio reference number for the transaction.
errorCode errorCode Appears only when transactionStatus is ERROR.
Possible values:
• 9100 (Error occurred on our server.)
• 9200 (Authorization token missing, invalid, or expired.)
• 9210 (Session expired after the user journey started.)
• 9300 (Error occurred transmitting image to our server.)
• 9400 (Error occurred during verification step.)
• 9800 (User has no network connection.)
• 9801 (Unexpected error occurred in the client.)
• 9810 (Problem while communicating with our server.)
• 9820 (File upload not enabled and camera unavailable.)
• 9835 (No acceptable submission in 3 attempts.)

1 Because HTTP GET parameters can be manipulated on the client side, they may be used for display purposes only.

Sample success redirect

https://www.yourcompany.com/success/?transactionStatus=SUCCESS&customerInternalReference=YOUR_REF&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Sample error redirect

https://www.yourcompany.com/error/?transactionStatus=ERROR&customerInternalReference=YOUR_REF&transactionReference=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&errorCode=9820

Supported browsers

Jumio offers guaranteed support for Netverify on the following browsers and the latest major version of each operating system.

Desktop

Browser Major version Operating system Supports
image upload		 Supports
HTML5 video stream
Google Chrome current +
1 previous		 Windows + Mac X X
Mozilla Firefox current +
1 previous		 Windows + Mac X X
Apple Safari current Mac X X
Microsoft Internet Explorer current Windows X
Microsoft Edge current Windows X X

Mobile

Netverify Web v4 does not support WebViews.

Browser name Major browser version Operating system Supports
image upload		 Supports
HTML5 video stream
Google Chrome current Android X X
Apple Safari current iOS X X

© Jumio Corp. 268 Lambert Avenue, Palo Alto, CA 94306