Netcetera Android 3DS SDK Demo Application
This documentation provides details about the use of the Netcetera Android 3DS SDK Demo Application and sample how the Netcetera Android 3DS SDK can be integrated.
The Netcetera Android 3DS SDK Demo Application represents an example integration of the Netcetera Android 3DS SDK. Along with this documentation, it serves as a guide for an easier integration of the Netcetera Android 3DS SDK in an application or a library.
The demo application simulates a real life payment action. It contains all cases from the frictionless and the challenge flows.
When the application is started, the initial screen is the payment details screen. Depending on the selected scenario, the application will present the appropriate flow.
For presenting the integration steps in proper order, the Netcetera Android 3DS SDK Demo Application is configured to work with Netcetera requestor backend which is an internal component and not available with the 3DS SDK product. The communication protocol between the merchant application and the PSP is proprietary for that particular PSP backend only and out of the scope for our Netcetera 3DS SDK products. For our use-case, we use the backend for:
- Versioning - Get the latest supported 3DS Protocol Version for the involved card number.
- Authentication - Process the authentication step of the 3DS authentication flow.
Appropriate adjustments to the application shall be made in order for the application to work and to perform transactions.
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
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
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
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 licence 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 on the initialization callback, 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
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.
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
release build type of the Netcetera Demo Application has set
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.
Proguard Gradle setup
build.gradle these configurations shall be listed in order to be taken into consideration one code optimization is performed.
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
debug build type, logging in
release builds can be on different level.
logback-android as dependency
To achieve this, first add
logback-android logging framework as dependency in
The configuration of
logback-android is done via adding
logback.xml configuration in the
Example Debug configuration for
Sample configuration for
debug builds that will usually be placed in
src/debug/assets/. It will log Netcetera Android 3DS SDK info level and above in Android Logcat:
Example Release configuration for
Sample configuration for
release builds that usually will be placed in
src/release/assets/. It will not log any Netcetera Android 3DS SDK in Android Logcat: