BAM Checkout Mobile Implementation Guide for Android This is a reference manual and configuration guide for the BAM Checkout Mobile product. It illustrates how to embed credit card and optional ID scanning into your app.

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

Contents BAM Checkout Mobile Implementation Guide for Android ...................................................... 1 Contents.................................................................................................................................. 2 Release notes ...................................................................................................................... 3 Contact ................................................................................................................................ 3 Credit card scanning ................................................................................................................... 4 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 .............................................................................................................. 8 Retrieving information ........................................................................................................ 9 Credit Card Retrieval API ...................................................................................................... 11 Two-factor authentication .................................................................................................... 12 ID scanning ............................................................................................................................... 13 Setup ..................................................................................................................................... 13 Architecture ...................................................................................................................... 14 Integration ............................................................................................................................ 14 Initializing the SDK ............................................................................................................ 15 Configuring the SDK .......................................................................................................... 15 Localizing labels................................................................................................................. 17 Customizing look and feel ................................................................................................. 17 Displaying the SDK ............................................................................................................ 17 Retrieving information (Fastfill) ........................................................................................ 20 Two-factor authentication .................................................................................................... 24

2

Release notes The current version of the Jumio SDK is 1.9.0. Visit BAM Checkout 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

Credit card scanning Setup The requirements for the SDK are:  Android 4.1 (API level 16) or higher  ARMv7 processor with Neon, ARM64-v8a, Intel x86 or Intel x86_64  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 necessary if using the custom scan view.

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

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","x86", "x86_64" } }

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","x86", "x86_64" 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:netswipe-resources:1.9.0@aar' compile 'com.jumio.android:javadoc:1.9.0' compile 'com.android.support:appcompat-v7:23.1.1' }

Note: If you use credit card and ID scanning in your app, add the following dependency: compile 'com.jumio.android:netverify-resources:1.9.0@aar'

5

Applications implementing the SDK shall not run on rooted devices1. Use either the below method or a self-devised check to prevent usage of SDK scanning functionality on rooted devices. NetswipeSDK.isRooted();

Call the method isSupportedPlatform to check if the device is supported. NetswipeSDK.isSupportedPlatform(this);

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

Initializing the SDK To create an instance of the SDK, perform the following call right before presenting the SDK's view controller. NetswipeSDK netswipeSDK = NetswipeSDK.create(yourActivity, "YOURAPITOKEN", "YOURAPISECRET", "YOURREPORTINGCRITERIA", JumioDataCenter.US);

Make sure that your merchant API token and API secret are correct, specify an instance of your activity and provide a reference to identify the scans in your reports (max. 100 characters or null). 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 Note: User journey related configurations do not apply for the custom scan view. Overwrite your specified reporting criteria to identify each scan attempt in your reports (max. 100 characters). netswipeSDK.setMerchantReportingCriteria("YOURREPORTINGCRITERIA");

To restrict supported card types, pass an ArrayList of CreditCardTypes to the setSupportedCreditCardTypes method. ArrayList creditCardTypes = new ArrayList(); creditCardTypes.add(CreditCardType.VISA); creditCardTypes.add(CreditCardType.MASTER_CARD); netswipeSDK.setSupportedCreditCardTypes(creditCardTypes);

You can enable the recognition of card holder name, sort code and account number. 1

In case of doubt, please consult a PCI QSA (Qualified Security Assessor).

6

Manual entry, expiry recognition and CVV entry are enabled by default and can be disabled. The user can edit the recognized expiry date if setExpiryEditable is enabled. netswipeSDK.setCardHolderNameRequired(true); netswipeSDK.setSortCodeAndAccountNumberRequired(true) netswipeSDK.setManualEntryEnabled(false); netswipeSDK.setExpiryRequired(false); netswipeSDK.setCvvRequired(false); netswipeSDK.setExpiryEditable(true);

Use setName to pass first and last name for name match if card holder recognition is enabled. The user can edit the recognized card holder name if setCardHolderNameEditable is enabled. Note: Levenshtein distance is used for name match. You can obtain the match result in the NetswipeCardInformation class. netswipeSDK.setName("FIRSTNAME LASTNAME"); netswipeSDK.setCardHolderNameEditable(true);

You can set a short vibration and sound effect to notify the user that the card has been detected. netswipeSDK.setVibrationEffectEnabled(true); netswipeSDK.setSoundEffect(R.raw.yourSoundFile);

Use setCameraPosition to configure the default camera (front or back). netswipeSDK.setCameraPosition(JumioCameraPosition.FRONT);

To enable flashlight after SDK is started, use the following method. netswipeSDK.setEnableFlashOnScanStart(true);

To show the unmasked card number during the user journey, disable the following setting. netswipeSDK.setCardNumberMaskingEnabled(false);

You can add custom fields to "Manual entry" and the confirmation view (keyboard entry or predefined values). netswipeSDK.addCustomField("idZipCode", "Zip code", "94306", InputType.TYPE_CLASS_NUMBER, "[0-9]{5}"); // addCustomField(String id, String title, String value, int inputType, String regularExpression); netswipeSDK.addCustomField("idState", "State", "Choose state", yourArrayList, false, "-- no value --"); // addCustomField(String id, String title, String hint, ArrayList values, boolean required, String resetValueText);

Use the following method to support the Adyen client-side-encryption. To successfully create an encrypted data object, enable expiry date, CVC and card holder name. Note: Transmission of the encrypted object to the Adyen payment gateway is not part of the SDK. 7

netswipeSDK.setAdyenPublicKey("ADYENPUBLICKEY");

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.Netswipe/Theme.Netswipe.NoActionBar as a parent style of your own theme.  Action Bar: title color and background using standard Android styles  Positive Button (Done): title color and background  Error dialog: text colors (retry possible/impossible)  Overlay on tablets: portrait and landscape ratio

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

NetswipeSDK.REQUEST_CODE);

Note: The default request code is 100. To use another code, override the public static variable NetswipeSDK.REQUEST_CODE before displaying the SDK. Custom scan view To use the custom scan view with a plain card scanning user interface, specify an instance of your class which implements the NetswipeCustomScanInterface and provide an instance of the class NetswipeCustomScanView. You will receive a NetswipeCustomScanPresenter object. Add yourNetswipeCustomScanView 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 NetswipeCustomScanView 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 yourNetswipeCustomScanView is added to your layout via xml, specify the below namespace to access the custom attribute yourNameSpace:ratio.

8

NetswipeCustomScanPresenter netswipeCustomScanPresenter = netswipeSDK.start(yourNetswipeCustomScanInterface, yourNetswipeCustomScanView);

Upon onNetswipeCameraAvailable within yourNetswipeCustomScanInterface, you can perform the following actions using the netswipeCustomScanPresenter:  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)  Stop card scanning public public public public public public public

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

Call onActivityPause in your activity upon onPause. public void onActivityPause();

Retrieving information Implement the standard method onActivityResult in your activity for successful scans and user cancellation notifications. Call netswipeSDK.destroy() once you received the result. You receive a Jumio scan reference for each try, if the Internet connection is available. For offline scans an empty String is added to the Arraylist scanReferences. Call cardInformation.clear() after processing the card information to make sure no sensitive data remains in the device's memory. The parameter EXTRA_ERROR_CODE contains the user cancellation reason. Note: The error codes 200, 210, 220, 240, 250, 260 and 310 will be returned. protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == NetswipeSDK.REQUEST_CODE) { // ArrayList scanReferences = data.getStringArrayListExtra(NetswipeSDK.EXTRA_SCAN_ATTEMPTS); if (resultCode == Activity.RESULT_OK) { // OBTAIN PARAMETERS HERE // YOURCODE // cardInformation.clear(); } else if (resultCode == Activity.RESULT_CANCELED) { // int errorCode = data.getIntExtra(NetswipeSDK.EXTRA_ERROR_CODE, 0); // String errorMessage = data.getStringExtra(NetswipeSDK.EXTRA_ERROR_MESSAGE);

9

// YOURCODE } // netswipeSDK.destroy(); } }

Custom scan view Instead of using the standard method onActivityResult, implement the following methods within yourNetswipeCustomScanInterface for camera, extraction and error notifications. Call netswipeCustomScanPresenter.clearSDK() and netswipeSDK.destroy() once you received the result. Upon onNetswipeError, you can show the error message and/or call netswipeCustomScanPresenter.retryScan() if retryPossible. Note: The error codes 200, 210, 220, 240, 260, 300, 310 and 320 will be returned. @Override public void onNetswipeCameraAvailable() { // YOURCODE } @Override public void onNetswipeExtractionStarted() { // YOURCODE like showing a progress indicator } @Override public void onNetswipeExtractionFinished(NetswipeCardInformation cardInformation, ArrayList scanReferences) { // YOURCODE // cardInformation.clear(); // netswipeCustomScanPresenter.clearSDK(); // netswipeSDK.destroy(); } @Override public void onNetswipeError(int errorCode, String errorMessage, boolean retryPossible, ArrayList scanReferences) { // YOURCODE like showing the error message and/or calling retry if retryPossible // netswipeCustomScanPresenter.retryScan(); // netswipeCustomScanPresenter.clearSDK(); // netswipeSDK.destroy(); }

Class NetswipeCardInformation Parameter

Type

cardType

CreditC ardType

cardNumber cardNumberGrouped

char[] char[]

Max. length

Description AMERICAN_EXPRESS, CHINA_UNIONPAY, DINERS_CLUB, DISCOVER, JCB, MASTER_CARD, PRIVATE_LABEL, VISA or STARBUCKS

16 19

Full credit card number Grouped credit card number

10

cardNumberMasked

char[]

19

cardNumberManuallyEntered cardExpiryMonth cardExpiryYear cardExpiryDate

boolean char[] char[] char[]

2 2 5

cardCVV cardHolderName

char[] char[]

4 100

cardSortCode

char[]

8

cardAccountNumber cardSortCodeValid cardAccountNumberValid nameMatch

char[] boolean boolean boolean

8

nameDistance encryptedAdyenString

int char[]

Method clear getCustomField

Parameter type -

Return type -

String

String

First 6 and last 4 digits of the grouped credit card number, other digits are masked with "X" True if manual entry, otherwise false Month card expires if enabled and readable Year card expires if enabled and readable Date card expires in the format MM/yy if enabled and readable Entered CVV if enabled Name of the card holder in capital letters if enabled and readable, or as entered if editable Sort code in the format xx-xx-xx or xxxxxx if enabled, available and readable Account number if enabled, available and readable True if sort code valid, otherwise false True if account number code valid, otherwise false True if successful name match (nameDistance