Netcetera 3DS SDK API

The API of the Netcetera 3DS SDK complies with the API defined by the EMVCo 3DS SDK Specification document. This section describes how the Netcetera 3DS SDK can be used to perform 3DS Authentication of payment or non-payment transactions.

Instantiation

Instance of the Netcetera Android 3DS SDK implementation of ThreeDS2Service can be acquired by calling ThreeDS2ServiceInstance.get(). This implementation holds single instance of the ThreeDS2Service and every invocation of ThreeDS2ServiceInstance.get() will return the same instance.

1
ThreeDS2Service threeDS2Service = ThreeDS2ServiceInstance.get();

UICustomization

The EMV 3DS 2.0 protocol defines API for the SDK for customization of the UI that is shown to the user during the challenge flow. This includes text color, fonts, background color, etc. A list of all methods is available in section 4.5 in the EMVCo 3DS SDK Specification.

Furthermore, Netcetera Android 3DS SDK adds support for the system wide dark mode available from Android 10. The Requestor application can enable this feature by calling the UICustomization.supportDarkMode(true) method on the UI customization object used for the SDK initialization. When enabled, the Netcetera Android 3DS SDK will follow the current android system theme as set in the system settings. To accommodate the additional styling needs of the dark mode, the Netcetera Android 3DS SDK extends the EMVCo protocol with additional methods listed bellow.

Note: The “dark” customization will only be applied when the Requestor application enables this feature, Android version is 10 or higher and dark mode is active in the system settings.

Class Method Description
UiCustomization supportDarkMode(boolean supported) Enables or disables the support for dark mode
Customization setDarkTextColor(String hexColorCode) Sets the dark mode text color
as hex string value
ButtonCustomization setDarkBackgroundColor(String hexColorCode) Sets the dark mode background color
as hex string value
ToolbarCustomization setDarkBackgroundColor(String hexColorCode) Sets the dark mode background color
as hex string value
LabelCustomization setHeadingDarkTextColor(String hexColorCode) Sets the dark mode heading text color
as hex string value
TextBoxCustomization setDarkBorderColor(String hexColorCode) Sets the dark mode border color
as hex string value

Initialization

In order to use the ThreeDS2Service for further actions, it needs to be initialized with ThreeDS2Service.initialize(...).

1
2
3
4
5
6
7
8
9
10
11
try {
  Context context = ...;
  ConfigParameters configParameters = ...;
  String locale = ...;
  UiCustomization uiCustomization = ...;
  threeDS2Service.initialize(context, configParameters, locale, uiCustomization);
} catch (InvalidInputException | SDKRuntimeException e) {
  // ...
} catch (SDKAlreadyInitializedException e) {
  // no-op, already initialized
}
Parameter Description
context Instance of Android application context. See Context.getApplicationContext in order how to get application context.
configParameters Instance of ConfigParameters created during SDK Configuration.
locale String that represents the locale for the app’s user interface.
uiCustomization Instance of UiCustomization created during SDK Configuration.

During initialization, security checks are performed and device information are collected. These parameters will be part of the Authentication and will be provided to the ACS via 3DS Server for risk analysis.

Fore more details about the security checks and their handling, refer to Security Features.

For more details on the device data that is collected, refer to EMVCo 3DS SDK Device Info Specification and EMVCo 3DS SDK Device Info Specification Version 1.1.

Warnings

After the security checks are performed, the SDK provides the outcome as list of Warning.

To obtain the result of these security checks call ThreeDS2Service.getWarnings().

1
2
3
4
5
6
try {
  List<Warning> warnings = threeDS2Service.getWarnings();
  // Handle warnings
} catch (SDKNotInitializedException e) {
  // ...
}

Each of the resulting Warning has Severity with value of LOW, MEDIUM and HIGH and it is up to the integrator to decide whether to act on each of them. For more details, please refer to Security Warnings.

The resulting warnings will be provided as part of Device Info in the Authentication.

Processing Screen

To indicate that a transaction is ongoing (such as ongoing Authentication Request or ongoing Challenge flow), a Processing Screen supplied by the 3DS SDK shall be shown by the requestor application. To get an instance of this processing screen, use Transaction.getProgressView(...). This method must be called from the main thread or else SdkRuntimeException will be thrown.

Processing Screen use cases and requriements for the requestor application: * (Required) EMVCo Requirement: While the 3DS Authentication Request is ongoing, the processing screen shall be shown for a minimum of two seconds by the requestor application, regardless of the authentication response time or result. EMVCo 3DS Specification * (Recommended) Netcetera 3DS SDK Requirement: If a 3DS Challenge flow is required after the Authentication Request, do not call ProgressView.hideProgress() before calling Transaction.doChallenge(...) as this will lead to a flicker on the screen since the 3DS SDK uses the same processing screen for starting the challenge flow (calls ProgressView.showProgress() internaly if is hidden). This processing screen is shown by the 3DS SDK until the the appearance of the first challenge screen. Furthermore, assuming no exception has been thrown by calling the Transaction.doChallenge(...) method, the 3DS SDK will hide the processing screen once the challenge is finished (when any of the ChallengeStatusReceiver methods has been called).

These requirements shall be implemented by the 3DS SDK integrator. For example, reference the Netcetera Demo Merchant application.

Note: Calling any method on the ProgressView object will have no effect once a successful Transaction.doChallenge(...) method call has occurred (no exception has been thrown). In this case, the Netcetera 3DS SDK takes control and handles the state of the processing screen.

Authentication

The 3DS Authentication flow starts with the authentication request that the 3DS Requestor Environment (Application or Library) sends it to the 3DS Server. The 3DS Server uses the data to compose the AReq that is sent to the DS and further forwarded to the appropriate ACS.

The ACS evaluates the data provided in the AReq and responds with ARes message to the DS, which then forwards the message to the 3DS Server. At the end the 3DS Server communicates the result of the ARes message back to the 3DS Requestor Environment.

The 3DS SDK generates authentication parameters that should be used for building the initial Authentication Request. All these parameters should be send to the 3DS Server, in the format the 3DS Server API defines. This parameters can be retrieved from Transaction object.

To obtain instance of Transaction, ThreeDS2Service.createTransaction(...) method can be used.

1
2
3
4
5
6
7
try {
  String directoryServerID = ...
  String messageVersion = "2.1.0";
  Transaction transaction = threeDS2Service.createTransaction(directoryServerID, messageVersion)
} catch(SDKNotInitializedException | InvalidInputException | SDKRuntimeException e) {
  // ...
}
Parameter Description
directoryServerID The ID of the Directory Server that will be used. Make sure there is already configuration for this DS made in DS Configuration.
messageVersion Protocol version according to which the transaction shall be created. If null highest supported value will be used.

After the Transaction object has been created, the AuthenticationRequestParameters can be obtained by calling Transaction.getAuthenticationRequestParameters().

1
2
3
4
5
6
try {
  AuthenticationRequestParameters authenticationRequestParameters = transaction.getAuthenticationRequestParameters();
  // Send request with AuthenticationRequestParameters to the 3DS Server
} catch (SDKRuntimeException e) {
  // ...
}

The parameters that are part of the AuthenticationRequestParameters are defined in chapter 4.12 in the EMVCo 3DS SDK Specification.

Starting of Challenge Flow

If the ACS assesses the transaction as high-risk, above certain threshold or that it requires higher level of authentication, it forces the Challenge Flow communication.

In case of Challenge Flow, the 3DS Requestor calls Transaction.doChallenge(...), and the SDK takes over the Challenge process. This method must be called on the main thread and before Activity.onSaveInstanceState(...) or else SdkRuntimeException will be thrown.

1
2
3
4
5
6
7
8
9
try {
  Activity activity = ... // getActivity();
  ChallengeParameters challengeParameters = ... // createChallengeParameters(authenticationResponse);
  ChallengeStatusReceiver challengeStatusReceiver = this;
  int timeOut = 5;
  transaction.doChallenge(activity, challengeParameters, challengeStatusReceiver, timeOut);
} catch (InvalidInputException e) {
  // ...
}

Once a challenge has been started, invocation on Transaction.doChallenge(...) and Transaction.close() will result in SdkRuntimeException, but the Challenge Flow won’t be interrupted nor the Transaction will be put in invalid state. When any result comes through the ChallengeStatusReceiver, calling of Transaction.doChallenge(...) and Transaction.close() can be called again.

For security purposes, the Activity that hosts the Challenge UI will have screenshots disabled with setting FLAG_SECURE to the Window.

Parameter Description
activity The Activity that is in the foreground of the application.
challengeParameters Instance of ChallengeParameters created with values from the Authentication Response.
challengeStatusReceiver Callback object that implements ChallengeStatusReceiver. It will be notified about the challenge status.
timeOut Timeout interval (in minutes) within which the challenge process must be completed. The minimum timeout interval is defined to be 5 minutes.

Requestor App URL

Starting with version 2.2.0 of the EMV 3DS Specification Protocol, the application (requestor) integrating the 3DS SDK can be called from another (authentication) application during an OOB challenge flow to indicate completed OOB authentication. To use this feature, the requestor application should define its app url and provide it to the 3DS SDK.

The app url can be provided to the 3DS SDK in the challenge parameters via the ChallengeParameters.setThreeDSRequestorAppURL(String threeDSRequestorAppURL) method. The inclusion of the this value in the challenge parameters is optional. If the app url is provided for irrelevant version of the 3DS Specification Protocol (example version 2.1.0), the 3DS SDK ignores it.

In order for the 3DS SDK to catch the potential call from the issuer authentication application and act accordingly, the requestor application needs to update the current Intent of the Activity that is used for starting the challenge - Transaction.doChallenge(Activity currentActivity, ...). This can be achieved by overriding the Activity.onNewIntent(Intent intent) method and setting the current intent to the newly received one.

1
2
3
4
5
@Override
protected void onNewIntent(Intent intent) {
  super.onNewIntent(intent);
  setIntent(intent);
}

For further information on how to define the threeDSRequestorAppURL value, you can check the EMVCo 3DS Specification.

As an example on how to use and handle the app url on the application side, you can check the Netcetera Android 3DS SDK Demo Application Documentation or its source code.

Challenge Flow Results

After invoking Transaction.doChallenge(...), Challenge Flow is started and the control of the UI is handed over to the 3DS SDK.

For the Netcetera Android 3DS SDK that means that the Activity provided via the Transaction.doChallenge(...) method should not be finished nor replaced by other Activity.

The DS Requestor has the controls back when any of the callback methods from the ChallengeStatusReceiver are invoked.

Implement a callback that implements the ChallengeStatusReceiver interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class MyChallengeManager implements ChallengeStatusReceiver {
 
  public void completed(CompletionEvent completionEvent) {
    // Handle successfully or unsuccessful completion of challenge flow 
  }
 
  public void cancelled() {
    // Handle challenge canceled by the user
  }
 
  public void timedout() {
    // Handle challenge timeout
  }
 
  public void protocolError(ProtocolErrorEvent protocolErrorEvent) {
    // Handle protocol error that has been send by the ACS
  }
 
  public void runtimeError(RuntimeErrorEvent runtimeErrorEvent) {
    // Handle error that has occurred in the SDK at runtime
  }
}

When any of the callback methods of the ChallengeStatusReceiver are invoked, the challenge flow is considered finished. As a result, the 3DS SDK dismisses the challenge screen, closes the transaction, cleans up resources and gives the 3DS Requestor control over the UI.

Closing of the Transaction

After the 3DS Authentication has finished, the 3DS Requestor should close the Transaction by calling Transaction.close() in order to clear references and avoid possible memory leaks.

This method should only be called when the Transaction.doChallenge(...) method is not called in a transaction. If invoked during an ongoing challenge, this method will throw SDKRuntimeException. At the end of the challenge flow, the 3DS SDK takes responsibility to cleanup resources and therefore this method is not required to be called.

After the transaction is closed and resources are cleaned up, any further operation on the Transaction object will result in a SDKRuntimeException.

Cleanup of the ThreeDS2Service

Similar as closing Transaction, in order to free up resources that are used by the ThreeDS2Service, the ThreeDS2Service.cleanup() shall be used. Once instance of ThreeDS2Service has freed up the used resources, it is in the same state as newly created ThreeDS2Service and can be used once again, but should go through Initialization one again.