Fastfill & Netverify Mobile Implementation Guide for Android This is a reference manual and configuration guide for the Fastfill and Netverify Mobile product. It illustrates how to embed the SDK into your app, retrieve information immediately (Fastfill) and perform the optional ID verification.

Copyright: Jumio Inc. 268 Lambert Avenue, Palo Alto, CA 94306

Contents Fastfill & Netverify Mobile Implementation Guide for Android ................................................ 1 Contents.................................................................................................................................. 2 Release notes ...................................................................................................................... 3 Contact ................................................................................................................................ 3 Setup ....................................................................................................................................... 4 Architecture ........................................................................................................................ 5 Integration .............................................................................................................................. 5 Initializing the SDK .............................................................................................................. 6 Configuring the SDK ............................................................................................................ 6 Localizing labels................................................................................................................... 8 Customizing look and feel ................................................................................................... 8 Displaying the SDK .............................................................................................................. 9 Retrieving information (Fastfill) ........................................................................................ 12 Callback ................................................................................................................................. 16 Netverify Retrieval API.......................................................................................................... 22 Netverify Delete API ............................................................................................................. 22 Global Netverify settings ...................................................................................................... 24 Application settings........................................................................................................... 24 Accepted IDs ..................................................................................................................... 24 Data settings ..................................................................................................................... 24 Supported cipher suites ........................................................................................................ 25 Two-factor authentication .................................................................................................... 26

2

Release notes The current version of the Jumio SDK is 1.9.0. Visit Fastfill & Netverify Mobile Release Notes to see additions, changes and fixes included in each release.

Contact If you have any questions regarding our implementation guide please contact Jumio Customer Service at [email protected] or https://support.jumio.com. The Jumio online helpdesk contains a wealth of information regarding our service including demo videos, product descriptions, FAQs and other things that may help to get you started with Jumio. Check it out at: https://support.jumio.com.

3

Setup The requirements for the SDK are:  Android 4.1 (API Level 16) or higher  ARMv7 processor with Neon, ARM64-v8a  Internet connection The following permissions are required by the SDK:

The following permissions are optional:

Note: On devices running Android Marshmallow (6.0) you need to acquire android.permissions.CAMERA dynamically before initializing the SDK. Use getRequiredPermissions you get a list of all required dangerous permissions. public static String[] getRequiredPermissions();

Using the SDK requires an activity declaration in your AndroidManifest.xml. Note: Not applicable for the custom scan view.

You can specify your own theme (see Customizing look and feel chapter) or remove the Action Bar by replacing Theme.Netverify with Theme.Netverify.NoActionBar. The orientation is restricted on phones, and sensor based or locked with the attribute android:screenOrientation on tablets. If you are using Proguard, add the following lines in its configuration. -keep class com.jumio.** { *; } -keep class jumiomobile.** { *; } -keep class net.sf.scuba.smartcards.IsoDepCardService {*;} -keep -keep -keep -keep

class class class class

org.jmrtd.** { *; } net.sf.scuba.** {*;} org.spongycastle.** {*;} org.ejbca.** {*;}

-dontwarn java.nio.** -dontwarn okio.** -dontwarn org.codehaus.**

4

-dontwarn org.ejbca.** -dontwarn org.spongycastle.**

Architecture You can filter which architecture to use by specifying the abiFilters. Note: The abiFilters command in the ndk closure affects the Google Play Store filtering. defaultConfig { ndk { abiFilters "armeabi","armeabi-v7a","arm64-v8a","mips","mips64" } }

The apk can be splitted based on the architecture if multiple apks should be uploaded to the Google Play Store. Google Play Store manages to deliver the appropriate apk for the device. splits { abi { enable true reset() include "armeabi","armeabi-v7a","arm64-v8a","mips","mips64" universalApk false } }

Note: You get an UnsatisfiedLinkError, if the app and the CPU architecture do not match.

Integration Use the SDK in your application by including the Maven repository with the following build.gradle configuration in Android Studio: repositories { maven { url 'http://mobile-sdk.jumio.com' } } dependencies { compile 'com.jumio.android:jumio-mobile-sdk:1.9.0@aar' compile 'com.jumio.android:netverify-resources:1.9.0@aar' compile 'com.jumio.android:javadoc:1.9.0' compile 'com.android.support:appcompat-v7:23.1.1' compile 'com.android.support:cardview-v7:23.1.1' }

Note: If you use Netverify and BAM Checkout in your app, add the following dependency: compile 'com.jumio.android:netswipe-resources:1.9.0@aar'

Call the method isSupportedPlatform to check if the device is supported. 5

NetverifySDK.isSupportedPlatform(this);

Check the Android Studio sample projects to learn the most common use.

Initializing the SDK To create an instance for the SDK, perform the following call as soon as your activity is initialized. NetverifySDK netverifySDK = NetverifySDK.create(yourActivity, "YOURAPITOKEN", "YOURAPISECRET", JumioDataCenter.US);

Make sure that your merchant API token and API secret are correct and specify an instance of your activity. If your merchant account is in the EU data center, use JumioDataCenter.EU instead. Note: Log into your Jumio merchant backend, and you can find your merchant API token and API secret on the "Settings" page under "API credentials". We strongly recommend you to store credentials outside your app.

Configuring the SDK Use the following method to pass first and last name for name match. Note: Levenshtein distance is used for name match. You can obtain the match result in the NetverifyDocumentData class. netverifySDK.setName("FIRSTNAME LASTNAME");

User journey Note: The following user journey configurations do not apply for the custom scan view. Use setCameraPosition to configure the default camera (front or back). netverifySDK.setCameraPosition(JumioCameraPosition.FRONT);

You can specify issuing country (ISO 3166-1 alpha-3 country code), ID type/s and/or document variant to skip their selection during the scanning process. Note: Fastfill does not support paper IDs, except German ID cards. netverifySDK.setPreselectedCountry("AUT"); netverifySDK.setPreselectedDocumentVariant(NVDocumentVariant.PLASTIC); ArrayList documentTypes = new ArrayList(); documentTypes.add(NVDocumentType.PASSPORT); documentTypes.add(NVDocumentType.DRIVER_LICENSE); netverifySDK.setPreselectedDocumentTypes(documentTypes);

To hide the country flag on the info bar, disable the following setting. 6

netverifySDK.setShowFlagOnInfoBar(false);

Transaction identifiers The merchant scan reference allows you to identify the scan (max. 100 characters). Note: Must not contain sensitive data like PII (Personally Identifiable Information) or account login. netverifySDK.setMerchantScanReference("YOURSCANREFERENCE");

Use the following property to identify the scan in your reports (max. 100 characters). netverifySDK.setMerchantReportingCriteria("YOURREPORTINGCRITERIA");

You can also set a customer identifier (max. 100 characters). Note: The customer ID should not contain sensitive data like PII (Personally Identifiable Information) or account login. netverifySDK.setCustomerId("CUSTOMERID");

Fastfill only To limit data extraction to be done on device only, enable setDataExtractionOnMobileOnly. netverifySDK.setDataExtractionOnMobileOnly(true);

ID verification Enable ID verification to receive a verification status and verified data positions (see Callback chapter). A callback URL can be specified for individual transactions (constraints see Callback URL chapter). This setting overrides your Jumio merchant settings. Note: Not possible for accounts configured as Fastfill only. netverifySDK.setRequireVerification(true); netverifySDK.setCallbackUrl("YOURCALLBACKURL");

You can enable face match during the ID verification for a specific transaction. This setting overrides your default Jumio merchant settings. netverifySDK.setRequireFaceMatch(true);

ePassport Use setEnableEpassport to read the NFC chip of an ePassport. netverifySDK.setEnableEpassport (true);

Note: If you are not using NFC scanning, you can remove the Spongycastle methods from the Proguard configuration. 7

-keep class org.spongycastle.** {*;}

Analytics Service Use the following setting to explicitly send debug information to Jumio. netverifySDK.setSendDebugInfoToJumio(true);

Note: Only set this property to true if you are asked by Jumio Customer Service. You receive a list of the current DebugSessionID by using getDebugID. This method can be called either after initializing or before dismissing the SDK. netverifySDK.getDebugID();

Localizing labels All label texts and button titles can be changed and localized using the standard strings.xml file. Just add the Jumio strings (see sample project under /res/values/strings.xml) and adapt them to your required language.

Customizing look and feel The SDK can be customized to fit your application’s look and feel by specifying Theme.Netverify/Theme.Netverify.NoActionBar as a parent style of your own theme.  Action Bar: title color and background using standard Android styles  Background: image using standard Android style  Search (country list): icon, text color, text cursor using standard Android styles  Info bar: text color, background color and background color of help menu  Positive button (Submit, OK): title color and background  Negative button (Retry): title color and background  Fallback button (Detection not working): title color and background  Help button: title color  Error dialog: text colors (retry possible and impossible)  Submission view: text color  Overlay on tablets: portrait and landscape ratio

8

Displaying the SDK To show the SDK, call the respective method below within your activity or fragment. Activity: netverifySDK.start(); Fragment: startActivityForResult(netverifySDK.getIntent(), NetverifySDK.REQUEST_CODE);

Note: The default request code is 200. To use another code, override the public static variable NetverifySDK.REQUEST_CODE before displaying the SDK. Custom scan view To use the custom scan view with a plain scanning user interface, specify an instance of your class which implements the NetverifyCustomSDKInterface. You will receive a NetverifyCustomSDKController object. NetverifyCustomSDKController netverifyCustomSDKController = sdk.start(yourNetverifyCustomSDKInterface);

Upon onNetverifyCountriesReceived within yourNetverifyCustomSDKInterface, specify country, document type and document variant to receive necessary scan parts. @Override public void onNetverifyCountriesReceived(HashMap countryList, String userCountryCode) { // YOURCODE // List netverifyDocumentParts = netverifyCustomSDKController.setDocumentConfiguration(netverifyCountries.get("USA", NVDocumentType.PASSPORT, NVDocumentVariant.PLASTIC); } NetverifyCountry methods: public String getIsoCode(); public Set getDocumentTypes(); public Set getDocumentVariants(NVDocumentType documentType); NetverifyDocumentPart methods: public NVScanMode getScanMode(); public NVScanSide getScanSide();

values: PASSPORT, ID_CARD, DRIVER_LICENSE NVDocumentVariant values: PAPER, PLASTIC NVScanMode values: MRZ, BARCODE, MANUAL, FACE, FACE_MANUAL, TEMPLATE_MATCHER, LINE_FINDER NVScanSide values: FRONT, BACK, FACE NVDocumentType

Upon onNetverifyResourcesLoaded within yourNetverifyCustomSDKInterface, start scanning by providing the first NetverifyDocumentPart, instances of the class NetverifyCustomScanView and NetverifyCustomConfirmationView, and an instance of your class which implements the NetverifyCustomScanViewInterface. You will receive a NetverifyCustomScanViewController object. 9

Add yourNetverifyCustomScanView to your layout and specify desired layout attributes using either  a certain width, and height as wrap_content  or a certain height, and width as wrap_content  or width and height as match_parent (full screen). Using width or height as wrap_content, the NetverifyCustomScanView attribute ratio needs to be set to any float value between screen width/screen height (e.g. portrait 720/1280 = ~ 0.6) and 4:3 (1.33). If yourNetverifyCustomScanView is added to your layout via xml, specify the below namespace to access the custom attribute yourNameSpace:ratio. xmlns:yourNameSpace="http://schemas.android.com/apk/lib/com.jumio.mobile.sdk" @Override public void onNetverifyResourcesLoaded() { // YOURCODE // NetverifyCustomScanViewController netverifyCustomScanViewController = netverifyCustomSDKController.startScanForPart(netverifyDocumentParts.get(0), yourNetverifyCustomScanView, yourNetverifyCustomConfirmationView, yourNetverifyCustomScanViewInterface); }

Upon onNetverifyCameraAvailable within yourNetverifyCustomScanViewInterface, you can perform the following actions using the netverifyCustomScanViewController:  Check if front and back camera available  Check if front camera used  Switch between front and back camera  Check if flash available  Check if flash enabled  Switch flash mode (on or off)  Check if scan in OCR mode (fallback) possible  Switch from default scan mode (MRZ or bar code) to OCR mode (fallback)  Stop card scanning public public public public public public public public public

boolean hasMultipleCameras(); boolean isCameraFrontFacing(); void switchCamera(); boolean hasFlash(); boolean isFlashOn(); void toggleFlash(); boolean isFallbackAvailable(); void startFallback(); void stopScan();

Call showShuttterButton to determine if the image will be taken manually. public boolean showShutterButton();

If so, display your shutter button and call takePicture() once clicked. public void takePicture();

10

Call stopScan in your activity upon onPause. Implement the following methods within  yourNetverifyCustomScanViewInterface for camera, extraction, confirmation view and US address notifications.  yourNetverifyCustomSDKInterface for scan part notifications. Upon onNetverifyPresentConfirmationView, you can hide the scan view and show the confirmation view (asking user to confirm the image), retry and/or confirm the scan. Note: yourNetverifyCustomScanView can be added to your layout by specifying any desired layout attributes. Upon onNetverifyNoUSAddressFound after a Fastfill US driver license back side scan in bar code mode, you can start a front side scan in OCR mode (fallback) to receive the address if needed and/or confirm the scan. Upon onNetverifyScanForPartFinished, call netverifyCustomScanViewController.destroy() to release all resources before scanning the next part until all parts are scanned. Once completed, call netverifyCustomSDKController.finish() to finish the scan. @Override public void onNetverifyCameraAvailable() { // YOURCODE } @Override public void onNetverifyExtractionStarted() { // YOURCODE like showing a progress indicator } @Override public void onNetverifyPresentConfirmationView() { // YOURCODE like hiding scan view and showing confirmation view (asking user to confirm the image), retrying and/or confirming scan // netverifyCustomScanViewController.retryScan(); // netverifyCustomScanViewController.confirmScan(); } @Override public void onNetverifyNoUSAddressFound() { // YOURCODE like starting Fastfill front side scan in OCR mode (fallback) and/or confirming scan // netverifyCustomScanViewController.startUSAddressFallback(); // netverifyCustomScanViewController.confirmScan(); } @Override public void onNetverifyScanForPartFinished(NetverifyDocumentPart documentPart, String image, boolean allPartsScanned) { // netverifyCustomScanViewController.destroy(); // YOURCODE like scanning next part until all parts scanned and/or finishing the scan if completed // NetverifyCustomScanViewController netverifyCustomScanViewController = netverifyCustomSDKController.startScanForPart(netverifyDocumentParts.get(1), yourNetverifyCustomScanView, yourNetverifyCustomConfirmationView, yourNetverifyCustomScanViewInterface); // netverifyCustomSDKController.finish();

11

}

Use the following methods to pause and resume the extraction. netverifyCustomScanViewController.pauseExtraction(); netverifyCustomScanViewController.resumeExtraction();

Retrieving information (Fastfill) Implement the standard onActivityResult method in your activity or fragment for successful scans (RESULT_CODE_SUCCESS or RESULT_CODE_BACK_WITH_SUCCESS) and user cancellation notifications (RESULT_CODE_CANCEL). Call netverifySDK.destroy() once you received the result. Note: Upon RESULT_CODE_BACK_WITH_SUCCESS, the submission was successful and the back button was pressed on the final screen. protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == NetverifySDK.REQUEST_CODE) { if (resultCode == NetverifySDK.RESULT_CODE_SUCCESS || resultCode == NetverifySDK.RESULT_CODE_BACK_WITH_SUCCESS) { // OBTAIN PARAMETERS HERE // YOURCODE } else if (resultCode == NetverifySDK.RESULT_CODE_CANCEL) { // String scanReference = data.getStringExtra(NetverifySDK.RESULT_DATA_SCAN_REFERENCE); // int errorCode = data.getIntExtra(NetverifySDK.RESULT_DATA_ERROR_CODE, 0); // String errorMessage = data.getStringExtra(NetverifySDK.RESULT_DATA_ERROR_MESSAGE); // YOURCODE } // netverifySDK.destroy(); } }

Custom scan view Instead of using the standard method onActivityResult, implement the following methods within yourNetverifyCustomSDKInterface for successful scans and error notifications. Call netverifyCustomSDKController.clearSDK() and netverifySDK.destroy() once you received the result. Upon onNetverifyError, you can show the error message and/or call netverifyCustomSDKController.retry() if retryPossible. Note: The error codes 100, 110, 120, 130, 140, 150, 160, 200, 210, 220, 230, 240, 250, 260 and 270 will be returned. @Override public void onNetverifyFinished(NetverifyDocumentData documentData, String scanReference) { // YOURCODE // netverifyCustomSDKController.clearSDK();

12

// netverifySDK.destroy(); } @Override public void onNetverifyError(int errorCode, String errorMessage, boolean retryPossible, String scanReference) { // YOURCODE like showing the error message and/or calling retry if retryPossible // netverifyCustomSDKController.retry(); // netverifyCustomSDKController.clearSDK(); // netverifySDK.destroy(); }

Class NetverifyDocumentData Parameter

Type

Max. length 3

selectedCountry

String

selectedDocumentType

NVDocumentType

idNumber

String

100

personalNumber

String

14

issuingDate expiryDate

Date Date

issuingCountry

String

3

lastName

String

100

firstName

String

100

middleName

String

100

dob

Date

First name of the customer Middle name of the customer Date of birth

gender

NVGender

Gender M or F

originatingCountry

String

3

street

String

100

Country of origin as ISO 3166-1 alpha-3 country code Street name

city

String

64

City

state

String

3

postalCode

String

15

Last two characters of ISO 3166-2:US state code Postal code

mrzData optionalData1

NetverifyMrzData String

50

MRZ data, see table below Optional field of MRZ line

13

Description ISO 3166-1 alpha-3 country code as provided or selected PASSPORT, DRIVER_LICENSE or IDENTITY_CARD as provided or selected Identification number of the document Personal number of the document Date of issue Date of expiry Country of issue as ISO 3166-1 alpha-3 country code Last name of the customer

Extraction (*1)

MRZ, bar code, OCR MRZ (MRP) Bar code, OCR MRZ, bar code, OCR MRZ, bar code, OCR MRZ, bar code, OCR MRZ, bar code, OCR Bar code, OCR MRZ, bar code, OCR MRZ, bar code, OCR MRZ

Bar code, OCR (except passport) Bar code, OCR (except passport) Bar code, OCR (except passport) Bar code, OCR (except passport) MRZ MRZ (TD1)

optionalData2

String

nameMatch

boolean

nameDistance

int

livenessDetected

boolean

placeOfBirth extractionMethod

String NVExtractionMethod

50

255

1 Optional field of MRZ line 2 True if successful name match (nameDistance