Netverify Multi Document Mobile
Implementation Guide for Android
This is a reference manual and configuration guide for the Netverify
Multi Document Mobile. It illustrates how to embed the SDK into
your application.
Copyright:
Jumio Inc. 268 Lambert Avenue, Palo Alto, CA 94306
Contents
Netverify Multi Document 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 ............................................................................................................ 7
Localizing labels................................................................................................................... 8
Customizing look and feel ................................................................................................... 8
Displaying the SDK .............................................................................................................. 8
Retrieving information ........................................................................................................ 8
Callback ................................................................................................................................. 10
Netverify Retrieval API.......................................................................................................... 13
Global Netverify settings ...................................................................................................... 14
Application settings........................................................................................................... 14
Supported cipher suites ........................................................................................................ 14
Two-factor authentication .................................................................................................... 15
2
Release notes
The current version of the Jumio SDK is 2.2.1. Visit Netverify Multi Document 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 support@jumio.com 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
Required permissions are linked automatically by the SDK.
The following permissions are optional:
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-feature android:name="android.hardware.camera" android:required="false"/>
Note: On devices running Android Marshmallow (6.0) you need to acquire
android.permissions.CAMERA dynamically before initializing the SDK.
Use getRequiredPermissions to get a list of all required dangerous permissions.
public static String[] getRequiredPermissions();
Using the SDK requires an activity declaration in your AndroidManifest.xml.
<activity
android:theme="@style/Theme.MultiDocument"
android:hardwareAccelerated="true"
android:name="com.jumio.md.MultiDocumentActivity"
android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"/>
You can specify your own theme (see Customizing look and feel chapter). 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 jumio.** { *; }
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.squareup.okhttp.** { *; }
-keep interface com.squareup.okhttp.** { *; }
-dontwarn com.squareup.okhttp.**
-dontwarn okio.**
-dontnote
4
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
Dependency
Mandatory
x
x
x
x
x
com.jumio.android:core:2.2.1@aar
com.jumio.android:md:2.2.1@aar
com.android.support:appcompat-v7:23.4.0
com.android.support:support-v4:23.4.0
com.squareup.okhttp:okhttp:2.7.5
Description
Jumio Core library
Multi Document library
Android native library
Android native library
HTTP client
Call the method isSupportedPlatform to check if the device is supported.
MultiDocumentSDK.isSupportedPlatform();
Check the Android Studio sample projects to learn the most common use.
5
Initializing the SDK
To create an instance for the SDK, perform the following call as soon as your activity is
initialized.
MultiDocumentSDK = MultiDocumentSDK.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.
Use setType to pass the document type.
multiDocumentSDK.setType("DOCUMENTTYPE");
Possible types:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
BS (Bank statement)
IC (Insurance card)
UB (Utility bill, front side)
CAAP (Cash advance application)
CRC (Corporate resolution certificate)
CCS (Credit card statement)
LAG (Lease agreement)
LOAP (Loan application)
MOAP (Mortgage application)
TR (Tax return)
VT (Vehicle title)
VC (Voided check)
STUC (Student card)
HCC (Health care card)
CB (Council bill)
SENC (Seniors card)
MEDC (Medicare card)
BC (Birth certificate)
WWCC (Working with children check)
SS (Superannuation statement)
TAC (Trade association card)
SEL (School enrolment letter)
PB (Phone bill)
USSS (US social security card)
SSC (Social security card)
CUSTOM (Custom document type)
The country needs to be in format ISO-3166-1 alpha 3 or XKX for Kosovo.
6
multiDocumentSDK.setCountry("USA");
Use the following property to identify the scan in your reports (max. 100 characters).
multiDocumentSDK.setMerchantScanReference("YOURSCANREFERENCE");
You can also set a customer identifier (max. 100 characters).
multiDocumentSDK.setCustomerId("CUSTOMERID");
Note: The customer ID and merchant scan reference should not contain sensitive data like
PII (Personally Identifiable Information) or account login.
Configuring the SDK
Custom Document Type
Use the following method to pass your custom document code. Maintain your custom
document code within your Jumio merchant backend under "Settings" - "Multi Documents" "Custom".
multiDocumentSDK.setCustomDocumentCode("YOURCUSTOMDOCUMENTCODE");
User journey
Use setCameraPosition to configure the default camera (front or back).
multiDocumentSDK.setCameraPosition(JumioCameraPosition.FRONT);
Use the following method to disable the help screen before scanning:
multiDocumentSDK.setShowHelpBeforeScan(false);
Use setDocumentName to override the document label on Help screen.
multiDocumentSDK.setDocumentName(“YOURDOCNAME”);
Transaction identifiers
Use the following property to identify the scan in your reports (max. 100 characters).
multiDocumentSDK.setMerchantReportingCriteria("YOURREPORTINGCRITERIA");
You can also set an additional information parameter (max. 255 characters).
Note: The additional information should not contain sensitive data like PII (Personally
Identifiable Information) or account login.
multiDocumentSDK.setAdditionalInformation("ADDITIONALINFORMATION");
7
A callback URL can be specified for individual transactions (constraints see Callback URL
chapter). This setting overrides your Jumio merchant settings.
multiDocumentSDK.setCallbackUrl("YOURCALLBACKURL");
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.MultiDocument as a parent style of your own theme. The individual customizing items
can be found in attrs.xml.
Displaying the SDK
To show the SDK, call the respective method below within your activity or fragment.
Activity: MultiDocumentSDK.start();
Fragment:
startActivityForResult(multiDocumentSDK.getIntent(),MultiDocumentSDK.REQUEST_CODE);
Note: The default request code is 200. To use another code, override the public static
variable MultiDocumentSDK.REQUEST_CODE before displaying the SDK.
Retrieving information
Implement the standard onActivityResult method in your activity or fragment for successful
scans (Activity.RESULT_OK) and user cancellation notifications (Activity.RESULT_CANCELED).
Call multiDocumentSDK.destroy() once you received the result.
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == MultiDocumentSDK.REQUEST_CODE) {
if (resultCode == Activity.RESULT_OK) {
// OBTAIN PARAMETERS HERE
// YOURCODE
} else if (resultCode == Activity.RESULT_CANCELED) {
// String scanReference =
data.getStringExtra(MultiDocumentSDK.EXTRA_SCAN_REFERENCE);
// int errorCode =
data.getIntExtra(MultiDocumentSDK.EXTRA_ERROR_CODE, 0);
// String errorMessage =
data.getStringExtra(MultiDocumentSDK.EXTRA_ERROR_MESSAGE);
// YOURCODE
}
// multiDocumentSDK.destroy();
}
8
}
Error codes
Code
100
210
220
230
250
260
Message
We have encountered a network communication problem
Authentication failed
280
Certificate not valid anymore. Please update your
application.
No Internet connection available
Cancelled by end-user
The camera is currently not available
9
Description
Retry possible, user decided to cancel
API credentials invalid, retry
impossible
Retry possible, user decided to cancel
No error occurred
Camera cannot be initialized, retry
impossible
End-to-end encryption key not valid
anymore, retry impossible
Callback
An HTTP POST with the following parameters is sent to your specified callback URL containing an application/x-www-form-urlencoded formatted
string with the result.
Note: Mandatory parameters are highlighted.
Parameter
scanReference
timestamp
transaction
document
Type
String
String
JSON object
JSON object
Max. length
36
Description
Jumio’s reference number for each scan
Timestamp of the response in the format YYYY-MM-DDThh:mm:ss.SSSZ
Transaction related data, see table below
Document related data if transaction status = DONE, see table below
Parameter "transaction"
date
status
source
merchantScanReference
customerId
additionalInformation
merchantReportingCriteria
clientIp
Type
String
String
String
String
String
String
String
String
Max. length
Description
Timestamp of the scan creation in the format YYYY-MM-DDThh:mm:ss.SSSZ
DONE
DOC_SDK
Your reference for each scan
ID of the customer
Additional information
Your reporting criteria for each scan
IP address of the client if provided for the Netverify Multi Document API
Parameter "document"
status
Type
String
Max. length
country
String
3
255
255
255
255
15
Description
Possible states:
 UPLOADED (default)
 EXTRACTED if type = SSC, country = USA and US social security card provided
 DISCARDED if type = SSC, country = USA and no US social security card provided
Possible countries:
 ISO 3166-1 alpha-3 country code
10
type
String
images
JSON array
 XKX (Kosovo)
Possible types:
 BS (Bank statement, front side)
 IC (Insurance card, front side)
 UB (Utility bill, front side)
 CAAP (Cash advance application, front and back side)
 CRC (Corporate resolution certificate, front and back side)
 CCS (Credit card statement, front and back side)
 LAG (Lease agreement, front and back side)
 LOAP (Loan application, front and back side)
 MOAP (Mortgage application, front and back side)
 TR (Tax return, front and back side)
 VT (Vehicle title, front side)
 VC (Voided check, front side)
 STUC (Student card, front side)
 HCC (Health care card, front side)
 CB (Council bill, front side)
 SENC (Seniors card, front side)
 MEDC (Medicare card, front side)
 BC (Birth certificate, front side)
 WWCC (Working with children check, front side)
 SS (Superannuation statement, front side)
 TAC (Trade association card, front side)
 SEL (School enrolment letter, front side)
 PB (Phone bill, front side)
 USSS (US social security card, front side)
 SSC (Social security card, front side)
 CUSTOM (Custom document type)
URLs to the images of the scan (JPEG or PNG)
To access an image, use the HTTP GET method and HTTP Basic Authentication with your merchant API token as
the "userid" and your API secret as the "password". Set "User-Agent: YOURCOMPANYNAME
YOURAPPLICATIONNAME/VERSION" (e.g. MyCompany MyApp/1.0.0) in the "header" section of your request.
The TLS protocol is required during the TLS handshake (see Supported cipher suites chapter) and we strongly
recommend using the latest version.
11
customDocumentCode
extractedData
String
JSON object
100
Your custom document code (maintained in your Jumio merchant backend) if type = CUSTOM
Extracted data if type = SSC, country = USA and status = EXTRACTED, see table below
Parameter
"extractedData"
signatureAvailable
ssn
firstName
lastName
Type
Max. length
Description
String
String
String
String
255
255
255
"true" if signature available, otherwise "false"
Social security number if readable
First name if readable
Last name if readable
Sample callback (URL-encoded POST): UPLOADED
timestamp=2016-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22AUT%22%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify
.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22UPLOADED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3A
%222014-1017T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22D
ONE%22%7D
Sample callback (URL-encoded POST): EXTRACTED
timestamp=2016-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22USA%22%2C%22extractedData%22%3A%7B%22firstName%22%3A%22FIRSTNAM
E%22%2C%22lastName%22%3A%22LASTNAME%22%2C%22signatureAvailable%22%3Atrue%2C%22ssn%22%3A%22xxxxxxxxx%22%7D%2C%22images%22%3A%5B%22htt
ps%3A%2F%2Fretrieval.netverify.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22EXTRACTED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3
A%222014-1017T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22D
ONE%22%7D
12
Sample callback (URL-encoded POST): DISCARDED
timestamp=2016-06-06T12%3A06%3A49.016Z&scanReference=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx&document=%7B%22type%22%3A%22SSC%22%2C%22country%22%3A%22USA%22%2C%22images%22%3A%5B%22https%3A%2F%2Fretrieval.netverify
.com%2Fapi%2Fnetverify%2Fv2%2Fdocuments%2Fxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx%2Fpages%2F1%22%5D%2C%22status%22%3A%22DISCARDED%22%7D&transaction=%7B%22customerId%22%3A%22CUSTOMERID%22%2C%22date%22%3
A%222014-1017T06%3A37%3A51.969Z%22%2C%22merchantScanReference%22%3A%22YOURSCANREFERENCE%22%2C%22source%22%3A%22DOC_SDK%22%2C%22status%22%3A%22D
ONE%22%7D
Netverify Retrieval API
If your server was not able to process the callback, which is the authoritative answer from Jumio, you can implement RESTful HTTP GET APIs to
retrieve status, details and image(s) for a specific scan. Find the Implementation Guide at the link below.
http://www.jumio.com/implementation-guides/netverify-retrieval-api/.
13
Global Netverify settings
In your Jumio merchant settings, you can configure the ID verification as follows.
Application settings
Callback URL
Provide a URL which meets the following constraints:
 HTTPS using the TLS protocol (we strongly recommend using the latest version)
 Valid URL (RFC-2396) using ASCII characters or IDNA Punycode
 IPs, ports, query parameters and fragment identifiers are not allowed
Whitelist the following IP addresses for callbacks, and use these to verify that the callback
originated from Jumio:

US data center: 50.57.26.248, 50.57.26.249, 69.20.24.138, 162.242.200.222
184.106.91.66, 184.106.91.67, 104.130.61.196, 146.20.77.156
You can look up the IP addresses with the host name "callback.jumio.com".

EU data center: 162.13.228.132, 162.13.228.134, 162.13.229.103, 162.13.229.104
You can look up the IP addresses with the host name "callback.lon.jumio.com".
Jumio will post callbacks to your HTTPS URL if you are using a valid certificate to ensure a
successful TLS handshake. If you are not receiving callbacks, please check the following
article.
Supported cipher suites
The following cipher suites (listed in server-preferred order) are supported by Jumio during
the TLS handshake:












TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_RSA_WITH_AES_256_GCM_SHA384
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_RSA_WITH_AES_128_GCM_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
Two-factor authentication
If you want to enable two-factor authentication for your Jumio merchant backend please
contact support@jumio.com. Once enabled, users will be guided through the setup upon
their first login to obtain a security code using the "Google Authenticator
15