Getting Started with the /n software 3-D Secure V2 Client Android Reference App Demo


This document is a guide through the setup and configuration of the /n software 3-D Secure V2 Client Android Reference App Demo (Reference App) with the UL 3DS Self Test Platform (STP). It explains the steps required to connect the app client as the System Under Test (SUT) to the necessary STP endpoints so that the platform tests can be executed and passed.

This guide assumes you already have a UL test platform account and can create a project with the SUT set in this case as 3DS Client. It will discuss steps of project creation relevant to configuration with the Reference App. More information on creating test platform accounts and projects is available in the documentaion section of the 3DS Self Test Platform homepage, in the 'UL 3DS Self Test Platform - Getting Started' document and the 'UL Reference Application for SDK Developers - Android' zip file.

Note that the Reference App is built on the UL Reference Application for SDK Developers - Android, which is downloadable (along with its documentation) from the test platform at the link above. The UL App allows developlers to extend it via their own SDK to test their implementation with the test platform. It offers sample templates and demo classes showing how to extend the app using an SDK. On the other hand, the /n software app replaces the template classes with functional classes demonstrating the Client component, creating a complete app which can pass tests out of the box. It uses the 3-D Secure V2 Client component to implement the SDK and extend the base Reference App.

In other words, the UI and project structure of the /n software app comes from the UL app, but the /n software app provides SDK classes (located in the com.ults.nsoftwaresdk package) to implement the base interfaces (package com.ul.a3ds.sdk.spec) included in the UL app. The spec package contains the interfaces in accordance with the 3DS SDK spec that must be implemented by the SDK classes that will provide the real implementation of the methods.


Preparing Reference App

The /n software Reference App is avaiable to download as a zip file from our website (link TBD).

To use the Reference App, you must have Android Studio 3.1.2 or higher, Android SDK Platform Android 8.1 API 27, Android SDK Platform-Tools 27.0.1, Android SDK Tools 26.1.1, Gradle 4.4, and Android Plugin Version 3.1.1. Upon importing and building the project, if your environment does not meet this requirements, you should be prompted by Android Studio to update them. You must also have the /n software 3D Secure V2 Java Edition product installed.

The first step is to download the Reference App zip file and unzip it, then import it into Android Studio. (TBD - jar included?) Copy the \lib\ipworks3ds.jar file from your installation of /n software 3D Secure V2 Java Edition (generally C:\Program Files\nsoftware\3-D Secure V2 Java Edition\lib\ipworks3ds.jar) and paste it into the \app\libs folder within the Reference App base project folder. If import references to ipworks3ds still do not resolve upon building, go to 'Build -> Edit Libraries and Dependencies' and a new jar dependency. Also be sure that the line implementation files('libs/ipworks3ds.jar') is included in your app build.gradle file under the dependencies section.

Configuring with Test Platform and Running App

Once the Reference App builds successfully, it must be configured for communication with the test platform before tests can be executed. Go to your test platorm project's configuration page and copy the SDK API Key found there (for Client projects). Open the file \app\scr\main\assets\ within the Reference App base folder and set it as theapi_key value. Rebuild your project, and it should be ready to run.

You can use an Android Emulator to test the Reference Application. To create one in Android Studio, go to Tools -> AVD Manager and use a API 27 system image. Run the Reference App with the chosen emulator. When the emulator boots and the app is loaded onto it, tests can be executed.

Executing Tests

Navigate to the Test Execution page for your test platform project. To select the first test, click 'Message Flow', then 'Frictionless Flow', then check 'TC_SDK_10001_001'. To start execution of the test, click the Run button. Unlike in Server system testing, this does not immediately initiate communication between the test platform and your system. Instead, any tests that have been executed on the test platform must be fetched by the app to complete the test process.

When the Reference App is first opened, three buttons are present on the screen - FETCH ALL TEST CASES, FETCH NEXT TEST CASE, and DELETE ALL TEST CASES. This screen is also accessible from other points in the app by tapping the menu icon in the top left corner to open the navigation drawer, then tapping TC Fetcher.

  • FETCH ALL TEST CASES will automatically run all test cases previously initiated on the test platform (this can take a long time depended on the number of tests initiated). The user will not need to tap buttons to submit the information they are presented with during the tests; they will be sent automatically (unlike with the FETCH NEXT TEST CASE button).
  • FETCH NEXT TEST CASE will execute only one test previously initiated on the test platform, and to proceed to the next test you will need to tap the button again once the test has completed. When each test is run, a message displaying the current test's name will briefly display at the bottom of the screen. Once every queued test has been executed by the system, a message will briefly display at the bottom of the screen reading that there are no more tests to execute.
  • DELETE ALL TEST CASES erases the queue of tests initiated on the platform. This is useful if you have initiated tests via the platform that you no longer wish to run, so that you can initiate new tests and run them instead.

For this example, use the FETCH NEXT TEST CASE button since only one test has been initiated ('TC_SDK_10001_001'). When the button is clicked, a processing dialog will appear as the test is fetched, then the UI for the Cardholder to enter the requested information will appear. Tap the send button. A waiting dialog will appear while the SDK is initialized, then the results of the authentication will be displayed along with a NEW TRANSACTION button. This button will return you to the TC Fetcher screen with the three button options.

If you initiate multiple tests and tap the FETCH ALL TEST CASES button, once the test is completed, instead of the results being displayed, the next test will immediately be started. In addition, any required input will automatically be returned, without you having to tap any buttons to submit it. The tests in the queue will be run automatically one after another until the queue is empty.

Different tests involve different flows. Tests involving a challenge require you to submit additional information (though this is always done automatically once the UI is displayed, even when using the FETCH NEXT TEST CASE button - no need to tap the submit button). Some tests will result in the transaction not being authenticated, and this information will be displayed as required when the test completes along with the NEW TRANSACTON button. This does not mean that the test has failed.

Currently, green checks do not appear next to completed tests as soon as they are passed on the system. Refreshing the test execution page will load the new checks and refresh the passed tests counter.

Reference App Project Notes

While the Reference App contains a large number of classes, many of these (package com.ul.a3ds.sdk.spec) are interfaces provided by the UL app which are implemented by corresponding classes in the com.ults.nsoftwaresdk package. Additionally, the spec interfaces are thoroughly documented to inform developers of the functions of the methods that must be overridden, which is helpful in understanding the logic of the app.

Many classes exist outside the spec and nsoftwaresdk packages, but many are simple, and the more complex logic is easier to follow because it corresponds to the relavent steps in the 3-D Secure 2.0 Protocol. To understand how the app executes tests, examine the app logic begininng with TestCaseActivity (package

Reference App Test Execution Logic

When TestCaseActivity is created (after the tests have been fetched via TestCaseFetcherFragment), the SDK is initialized in the onCreate method. Once this async initialization is completed, the TestCaseActivity.OnIsCompleted method is called, which calls TransactionManager.getInstance().StartAResAResFlow();. This gathers SDK (using Client) and device info and uses it to build a proprietary Authentication Request message (pAReq), which is then sent to the platform simulation of the 3DS Server.

When the resulting ARes message is received from the Server, the TransactionManager.GetResponse method is called by a network event. A proprietary SDK Information Request is built from the ARes to be sent to the test platform to notify it that the test is completed, and the TransactionStatus is determined.

If no challenge is required, TransactionManager.FinishTestCaseExecution is called which starts the ResultActivity to display the authentication result to the user and calls TestCaseRunner.FinishTestCaseExecution which notifies the test platform of the test results.

If a challenge is required, the challenge paramaters are set based on the data provided in ARes, and the TransactionManager.ExecuteChallenge method is called. This calls the Transaction.DoChallenge method (via the ExecuteChallengeAsync.Execute method), which builds and sends to the platform ACS simulation the Challenge Request message (CReq) from the paramaters provided using Client.SendChallengeRequest.

The Client component then receives the resulting Challenge Response (CRes) from the ACS simulation and uses the ACSUIType provided to start the proper activity for the desired user input. The challenge information is automatically filled in the UI and submitted (without user interaction), and SDKChallengeUtils.SubmitCReq is called, passing the entered data and paramaters to the ClientStatusChallengeReceiver class. Here the Client component builds and sends the CReq.

If the response indicates the challenge was not completed, the challenge UI and submission process is repeated. Otherwise, the authentication is complete and the same final steps involving displaying the results and notifying the platform are followed.

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