Getting Started with the 3DS SDK

/n software 3-D Secure includes a 3DS SDK that can be used to support 3-D Secure V2 authentication natively in a mobile application. The following sections provide guidance on getting started with the /n software 3DS SDK.

Contents

Android

First and foremost, add the ipworks3ds_sdk.aar to your app:

  1. Copy the ipworks3ds_sdk.aar to the /libs folder in your module.
  2. Import the SDK by adding this line to your m,odule build.gradle file:
    implementation(name: 'ipworks3ds_sdk', ext: 'aar')

SDK Initialization

Initialize the SDK. Depending on the 3DS Requestor application implementation, a ThreeDSService instance is created either during startup of the 3DS Requestor app (as a background task), or when a transaction is initiated. The state of the service is maintained until the cleanup method is called.

In the demo application, initialization is done at startup via the initializeSDK method in the MainActivity:

ThreeDS2Service.INSTANCE.initialize(getApplicationContext()),
										configParameters,
										Null,
										Null,
										newMyClientEventListener());

The parameters this initialize method takes are as follows:

  • context: An instance of Android application context. In the demo, this is retrieved using getApplicationContext, an Android activity method.
  • configParameters: Configuration information that shall be used during initialization. See the ConfigParameters section below.
  • s: Locale - a string that represents the locale for the app's user interface (e.g. "en-US"). For future use.
  • uiCustomization: UI configuration information that is used to specify the UI layout and theme (fonts, colors, etc.) See the UiCustomization section below.
  • clientEventListener: A listener to hook in to all the events for the underlying Client component (for logging, etc.) See the Client component documentation for details on the available events. The demo app implements the handler via a MyClientListener class.

ConfigParameters

Configuration parameters that are required by the 3DS SDK for initialization. Different parameters fall into a few "groups":

  • DirectoryServerInfo: Used to add keys and certificates for different directory servers. For example:
    List<ConfigParameters.DirectoryServerInfo> directoryServerInfoList = new ArrayList<>();
    	directoryServerInfoList.add(new ConfigParameters.DirectoryServerInfo(UL_DS_RSA_ID, UL_DS_RSA_CERT, UL_DS_CA));
    	directoryServerInfoList.add(new ConfigParameters.DirectoryServerInfo(UL_DS_EC_ID, UL_DS_EC_CERT, UL_DS_CA));
    	ConfigParameters configParameters = new ConfigParameters.Builder(directoryServerInfoList);
    Passed in to Builder method.
  • deviceParameterBlacklist: A list of device parameters NOT to pull from the device. By default, the SDK will pull as many device parameters as it can. This setting group can be used to instruct the SDK not to pull certain parameters.
  • maliciousApps: Apps that are recognized as malicious. If the apps are installed, a security warning (SW02) will be raised. There are some default malicious apps configured by default:
    • de.robv.android.xposed
    • de.robv.android.xposed.installer
    • com.saurik.substrate
  • trustedAppStores: A security warning (SW02) will be raised if the app is not installed from the Google app store. trustedAppStores can add additional app stores as trusted.
  • appSignature: A security warning (SW02) is raised if this value does not match the app signature. The user should store the app signature to their server and retrieve it (and set it here). Note that this should not be hardcoded in the app for security reasons. If this value is not specified, the SDK will see the signature as invalid.
  • clientConfig: Configuration settings that will be passed on to the underlying Client component. A list of available options can be found in the documentation for the Client component.

UiCustomization

Should the 3DS Requestor wish to have its own look-and-feel in the challenge pages, the UICustomization class is used. This class allows the customization of Buttons, Labels, TextBoxes, and Toolbars. For example, the following will configure buttons with dark red backgrounds and white font:

UiCustomization customUI = new UiCustomization();
	ButtonCustomization customButton = new ButtonCustomization();
	customButton.setTextColor("#FFFFFF"); // White
	customButton.setBackgroundColor("#951728"); // Dark red
	customUI.setButtonCustomization(customButton, UiCustomization.ButtonType.CANCEL);
	customUI.setButtonCustomization(customButton, UiCustomization.ButtonType.CONTINUE);
	customUI.setButtonCustomization(customButton, UiCustomization.ButtonType.NEXT);
	customUI.setButtonCustomization(customButton, UiCustomization.ButtonType.RESEND);
	customUI.setButtonCustomization(customButton, UiCustomization.ButtonType.SUBMIT);

Here is the resulting Submit button for a Single-Select challenge:

The SDK does security checks and collects device information during initialization.

A list of warnings produced during the 3DS SDK initialization can be retrieved using the getWarnings method. You can check these and determine whether or not to proceed with the checkout.

Transaction Initiation

Call the createTransaction method to start a transaction. A reference should be kept for this transaction through the entire 3-D Secure process. When the transaction is complete, it shuold be closed via the Transaction object's close method. This method takes the directory server ID, which points to a DS configuration added in the configParameters above. The second parameter is a protocol version (a string, i.e. 2.1.0 or 2.2.0).

In the demo application, a TransactionManager class is used to manage the transaction. This includes the createTransaction method (to create a new transaction), which in the demo is called when getting the authentication request parameters (there is a check to see if the transaction is null, and if so, create a new one). This can also be called by itself, prior to calling getAuthenticationRequestParameters.

Display a Progress Dialog

When the app is communicating with the server (where 3DS Server will step in to perform the authentication request), a progress dialog will be displayed to the user. This is done in the demo app like so:

// show progress dialog during the AReq/ARes flow
	// The progress dialog will be closed by the SDK
	TransactionManager.getInstance().showProgressDialog();

Start Authentication

Request parameters will need to be obtained and sent to the server in order to start the 3-D Secure authentication process. The getAuthenticationRequestParameters method will encrypt the device information that it collects during initialization. The returned AuthenticationRequestParameters object is defined in the EMVCo SDK specification, and contains the fiuelds defined there, as well as an AuthRequest field:

  • SDKTransactionId
  • DeviceData: Device data collected by the SDK during initialization and encrypted using the DS key.
  • SDKEphemeralPublicKey
  • SDKAppId
  • SDKReferenceNumber: Assigned to our SDK by EMVCo after certification.
  • MessageVersion: From createTransaction, or a default value from the SDK (2.1.0).
  • AuthRequest

AuthRequest corresponds to the output of the Client component's GetAuthRequest method. This string would be passed, along with some additional data (e.g. purchase amount, card number - essentially any information needed in the Server component that originates on the device), to the 3DS Server to start the authentication process (i.e. Server component's SendAuthRequest method). In the demo application, this is done in the POST2Requestor_StartAReqAResFlow method.

On the server side, the AuthRequest data would be passed to the 3DS Server component (ClientAuthRequest property) as part of the configuration before calling SendAuthRequest. When SendAuthRequest returns, the Server component's ClientAuthResponse property would be returned in the response to the app.

Handle the Server Response

Based on the data that is returned from the 3DS Server, the app has to devicde whether a challenge is required or not. It is up to the server what will be returned when no challenge is needed (frictionless flow). The test server used by the demo app simply sends back an "OK" string.

If a challenge is required, we need to create the ChallengeParameters (using the authResponse) and call doChallenge. When doChallenge is called, control of the UI is handed over to the 3DS SDK. The demo app does this in the startChallenge method (TransactionManager). The challenge will be performed by the SDK, and when finished the appropriate ChallengeStatusReceiver event will fire (completed, cancelled, etc.)

3DS Authentication Complete

After a challenge phase, the Transaction must first be closed via the Transaction object’s close method. Each Transaction can be used only once. A new transaction would require a new Transaction instance to be used.

The 3DS Requestor App can query for the transaction results from the 3DS Server, as the results will have been posted to the 3DS Server prior to the final challenge response being returned to the SDK. This communication is out of the scope of the 3DS protocol itself.

Possible valuies for the transaction result (transaction status) are:

  • Y: Order completed successfully / Authentication successful
  • A: Order completed successfully / Attempts processing performed
  • N: Order denied / Not authenticated (denied)
  • R: Order denied / Authentication rejected
  • U: Order failed due to technical reasons / Authentication could not be performed

Clean up the ThreeDS2Service Instance

The cleanup method frees up resources that are used by the 3DS SDK. It is called only once during a single 3DS Requestor App session:

ThreeDS2Service.INSTANCE.cleanup(applicationContext);

Notes on Application Permissions

The SDK itself does not require any permissions; it will use only the permissions that the 3DS Requestor application has requested. The app should require permission before the SDK is initialized. This is required by the specification and some device parameters will not be available if permission is not granted.


We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.