Netcetera Android 3DS SDK Demo Application

Requestor Application

The Netcetera Android 3DS SDK Demo Application serves as an example integration of the Netcetera Android 3DS SDK, entirely written in Kotlin. Together with this documentation, it provides a guide for integrating the Netcetera Android 3DS SDK into an application or library.

This demo application simulates a real-life payment action, encompassing all scenarios from both the frictionless and challenge flows.

Upon starting the application, users are greeted with the payment details screen. Depending on the selected scenario, the application will present the appropriate flow.

To present the integration steps in the correct order, the Netcetera Android 3DS SDK Demo Application is configured to work with the Netcetera requestor backend, which is an internal component not included in the 3DS SDK product. The communication protocol between the merchant application and the PSP is proprietary and specific to the PSP backend, falling outside the scope of our Netcetera 3DS SDK products.

For our use case, we utilize the backend for:

• Versioning: Obtaining the Directory Server ID and the latest supported 3DS Protocol Version for the involved card number.
• Authentication: Managing the authentication step of the 3DS authentication flow.

Appropriate adjustments to the application are necessary for it to function correctly and process transactions.

App architecture

The Netcetera Android 3DS SDK Demo Application implements the MVVM architecture pattern, split into an UI, Domain and Data layer. The UI layer consists of an Activity which renders the View and a ViewModel which handles the screen logic. The business logic of the application is located in the Domain layer and it is handled by UseCases. Lastly, the application stores and accesses data in the Data layer via Repositories.

Example structure of a screen implementation, the src/main/.../presentation/screens/splash folder contains the following files:

• SplashActivity.kt - contains the view logic of the splash screen.
• SplashViewModel.kt - contains the splash screen logic for interacting between the view and use cases

Example structure of use case, the src/main/.../domain/usecase folder contains the following files:

• InitializeThreeDSSDKUseCase.kt - use case for initialization of ThreeDS2Service

The same structure is followed for the other screen implementations and use cases.

Intended to be used by different use cases, the Android SDK demo application uses ThreeDS2Service as singleton instance in a Hilt module.

The creation of the transaction in the Android SDK Demo Application is performed by tapping on the Submit button. The predefined scenarios of the frictionless and challenge flows can be found in TransactionModelRepository. By selecting a scenario in PrefillDataActivity, you select the example which will be shown once you tap on Submit.

The authentication request is created in AuthenticationRequest.Companion#buildAppRequest. Depending on the response received from the server, the application decides whether or not to opt for a challenge. An example implementation of the Authentication Flow can be found in PerformAuthenticationFlowUseCase.

SDK Usage

The Netcetera Android 3DS SDK is initialized by invoking InitializeThreeDSSDKUseCase in the BaseSplashViewModel at the start of the Netcetera 3DS Android Demo Merchant application. For the initialization to be successful, the Netcetera Android 3DS SDK needs to be configured with a valid DS Configuration and a valid API key (this value is configured in gradle.properties). Here is how this is done in the Netcetera 3DS Android Demo Merchant application:

Once the SDK has been initialized, you can access the warnings generated during the initialization. This is done by calling the ThreeDS2Service#getWarnings() method. In the example above, the warnings are returned with the UseCase result, but you can ask for them anytime as long as the underlying ThreeDS2Service is initialized.

The creation of transaction and sending of the Authentication Request is performed by tapping on the Submit button on the checkout screen. This logic can be found in Perform3DSFlowUseCase, which is invoked in the BaseCheckoutViewModel.

The versioning request is used to get the directoryServerID for the given card number, as well as the highestCommonSupportedVersion value if LATEST_VERSION is selected for the message version. The versioning response contains additional data that can be useful for an integrating app. For more information on versioning, refer to the Netcetera 3DS Server SaaS documentation page.

App URL

Starting with version 2.2.0 of the EMV 3DS Specification Protocol, the application integrating the 3DS SDK can be called (brought to foreground) from another (authentication) application during an OOB challenge flow to indicate completed OOB authentication. The Netcetera demo application provides sample implementation of this feature summarized bellow.

The activity that calls the challenge flow must be open for calls from an outside application for a specific uri - app url. Moreover, this activity should act as a "singleton" so that the instance holding the ongoing challenge flow is brought to foreground (singleTask) instead of launching new activity instance.

Next, this activity needs to update its current intent when new intent is received in order for the Netcetera Android 3DS SDK to detect that it was brought to foreground from another application using the provided app url.

Finally, the application sets the correct app url for the ongoing transaction in the challenge parameters ChallengeParameters.setThreeDSRequestorAppURL(String threeDSRequestorAppURL) used for starting the challenge. The threeDSRequestorAppURL value consists of the scheme and host values declared in the activity manifest configuration and a query parameter transID with the value of the SDK Transaction ID (AuthenticationRequestParameters.getSDKTransactionID()) of the ongoing Transaction. Therefore, considering the aforementioned activity manifest configuration, for a Transaction having SDK Transaction ID of "3800cde2-bba6-11ea-b3de-0242ac130004", the threeDSRequestorAppURL would be equal to https://ndm-app.netcetera.com/ndm?transID=3800cde2-bba6-11ea-b3de-0242ac130004

Proguard configuration

The release build type of the Netcetera Demo Application has set minifyEnabled to true, meaning that during the release task, the source code of the application and its dependencies will go through optimization and obfuscation.

For better tuning which parts of the code are to be optimized and obfuscated, Proguard is used.

Proguard is taken as example configuration as most common measure of simple protection of a given application or library. The same approach should be used when using other similar tools.

Logging

As the Netcetera Android 3DS SDK uses SLF4J for logging purposes, one simple configuration is to use SLF4J implementation that is using the Android Logcat. Additionally by providing different configurations for release and debug build type, logging in debug and release builds can be on different level.