Pure 3DS Interface

1 Overview
2 Supported Versions
3 Actors & flow diagram
4 Initialization
- 4.1 Android
- 4.2 iOS
5 The warnings
6 Create Transaction
- 6.1 Android
  - 6.1.1 Option #1
  - 6.1.2 Option #2 (Enables SCA functions in the transaction, recommended)
- 6.2 iOS
  - 6.2.1 Option #1
  - 6.2.2 Option #2 (Enables SCA functions in the transaction, recommended)
7 Getting Authentication parameters
- 7.1 The Progress Dialog
  - 7.1.1 Android
  - 7.1.2 iOS
8 The challenge flow
- 8.1 Android
- 8.2 iOS
9 Completing Authentication
10 Closing Transaction
- 10.1 Android
- 10.2 iOS

Overview

The uSDKs implement the pure 3DS v2 protocol as specified by EMVco - https://www.emvco.com/emv-technologies/3d-secure. This section explains the interface in detail as well as provides code snippets to get started promptly.

The sample applications for Android and iOS can be used to see the matters discussed below in action.

Supported Versions

Both, uSDK 6.3 and 6.4 support the Pure 3DS Interface.

Actors & flow diagram

The following diagram is a sequence that helps grasping the pure 3DS v2 API interface concepts as well as visualizing the actors and their interactions. The actors are:

The requestor’s mobile application that has the Android or iOS uSDK integrated
The uSDK itself
The requestor’s backend server side application. That’s where the requestor usually maintains a database of products and users. This is where the authenticate call to a 3DS server call made from.
A 3DS Server

The following sub-sections describe each of the concepts in details.

Initialization

Before use, the uSDK has to be instantiated and initialized. This usually is done once during application's session when application is launching. At this point the uSDK captures and caches device information and prepares itself to serve.

The method accepts a couple of arguments, the most important one the configParams which is used to pass the license key as well as any additional directory servers to the uSDK at runtime. The code examples below show how the license key is passed.

See Directory Servers section for more details about how to use configParams to pass additional directory servers.

Android

// Create an instance of the 3DS service:
ThreeDS2Service service = new UsdkThreeDS2ServiceImpl();

// Prepare ConfigParameters and put the license key in it
ConfigParameters configParams = new ConfigParameters();
configParams.addParam(UsdkThreeDS2ServiceImpl.USDK_CONFIG_PARAMETER_GROUP, 
  UsdkThreeDS2ServiceImpl.LICENSE_PARAMETER_KEY, 
  licenseKey);

// Initialize the uSDK
service.initialize(context, configParams, locale, uiCustomization);

The example above also shows how the license key is passed to the uSDK

context - An Android context, it can be an Application instance or some other Context instance.
configParams - an instance of org.emvco.threeds.core.ConfigParameters class used for passing additional configuration parameters down to the SDK.
locale - the locale as a String, a value like en_US would be good. Also it is possible to pass null value which will make it use the default locale on the device.
uiCustomization - an instance of org.emvco.threeds.core.ui.UiCustomization class used to specify how the challenge screen should look like. The matter is documented in detail in the Customizing the challenge screen section.

On Android, the initialization is an asynchronous task, so the app has to set up a listener to be notified when the initialization finishes. The complete example would be this:

ThreeDS2Service service = new UsdkThreeDS2ServiceImpl();

ConfigParameters configParams = new ConfigParameters();
configParams.addParam(UsdkThreeDS2ServiceImpl.USDK_CONFIG_PARAMETER_GROUP, 
  UsdkThreeDS2ServiceImpl.LICENSE_PARAMETER_KEY, 
  licenseKey);

BroadcastReceiver listener = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        Log.d(TAG, intent.toString());
        LocalBroadcastManager.getInstance(context).unregisterReceiver(this);

        if (!intent.getBooleanExtra(UsdkThreeDS2ServiceImpl.INITIALIZATION_ACTION_EXTRA_SUCCESS, false)) {
            throw new RuntimeException("Failed to initialize SDK"
                    + ", code: " + intent.getStringExtra(UsdkThreeDS2ServiceImpl.INITIALIZATION_ACTION_EXTRA_ERROR_CODE)
                    + ", type: " + intent.getStringExtra(UsdkThreeDS2ServiceImpl.INITIALIZATION_ACTION_EXTRA_ERROR_TYPE)
            );
        }

        // it is OK to start use the `service` object as it has been successfully initialized
    }
};

LocalBroadcastManager.getInstance(this).registerReceiver(
    listener, 
    new IntentFilter(UsdkThreeDS2ServiceImpl.INTENT_INITIALIZATION_ACTION)
);

service.initialize(context, configParams, locale, uiCustomization);

iOS

// Prepare ConfigParameters and put the license key in it
private var configParams: UConfigParameters {
    let params = UConfigParameters()
    // kUUSDKGroup and kUUSDKParamLicenseKey are provided in UConstants.h. See docs there
    params.addParam(kUUSDKGroup, name: kUUSDKParamLicenseKey, value: mSigniaProvidedicenseKey)
    return params
}

// Initialize the uSDK
UThreeDS2ServiceImpl.shared.initialize(configParams, locale: "en_us", uiCustomization: uiCustomization)

The example above also shows how the license key is passed to the uSDK

configParams - An instance of UConfigParameters used for passing additional configuration parameters to the SDK.
locale - the locale as a String. Non-optional.
uiCustomization - An instance of UUiCustomization class used to specify various elements of the challenge screen UI. The matter is documented in detail in the Customizing the challenge screen section.

The warnings

After a successful initialization of the uSDK, the app may call an optional getWarnings method to gather any warnings uSDK generated during the initialization. The complete Warnings conception is described in detail in its own section later in the documentation.

Create Transaction

At some point the app decided to start a 3DS transaction. This can be done at the moment the user taps the “Purchase” button in the app.

Android

There are two methods there to create a transaction. The first one is the one required per the 3DS v2 specification while the second one is more generic and is recommended to use when SCA functionality is required.

Option #1

Option #2 (Enables SCA functions in the transaction, recommended)

iOS

Same two options are applicable for iOS:

Option #1

Option #2 (Enables SCA functions in the transaction, recommended)

Getting Authentication parameters

Once there’s a transaction instance created, it is the time to call its getAuthenticationRequestParameters method. The result of this method is a plain object with a bunch of fields that need to be literally conveyed to 3DS server. See the “Deliver purchase information & authentication params” label in the diagram above for how this is conveyed to the backend and later to a 3DS Server.

The response received from 3DS Server is an ARes. Either the backend or the mobile application has to inspect it to see the transStatus value the 3DS server returned. The following matrix could be used as a starting point but it is strongly recommended to familiarize with the 3DS specification here.

ARes.transStatus	Description

ARes.transStatus	Description
Y	Order completed successfully / Authentication successful
A	Order completed successfully / Attempts processing performed
D	Decoupled authentication is being performed
C	Continue to Challenge Flow
N	Order denied / Not authenticated (denied)
R	Order denied / Authentication rejected
U	Order failed due to technical reasons / Authentication could not be performed

So, for instance, if ARes.transStatus was Y then the authentication has succeeded.

The Progress Dialog

While the application conveys the parameters to the backend and then to a 3DS Server, it is recommended to display a progress dialog, given that is normally a long and time consuming operation. The uSDK provides a component for that displaying the DS logotype and a spinning image to entertain the user.

Android

iOS

The challenge flow

If ARes.transStatus is C then that means ACS opts to challenge the user. For that the mobile application calls the doChallenge method on the transaction instance.

The result of challenge flow is then called back to the application as part of ChallengeStatusReceiver interface/delegate.

Android

activity - activity instance that invoked doChallenge method
challengeParameters - the data ACS puts in the ARes for the uSDK to conduct a challenges flow. This is an instance of ChallengeParametersclass that the mobile application has to construct literally using the corresponding data from ARes.
challengeStatusReceiver - an implementation of ChallengeStatusReceiverinterface which acts as a callback object for notifying the application about the result of challenging.
timeOut - an interval, in minutes, within which the challenge process must be completed. The minimum possible value is 5 minutes. The recommended value for this parameter is 10 minutes.

iOS

Simply call doChallenge and the SDK's UI will handle the challenge process and notify the app upon completion of the challenge.

There’s also a convenience method that supports do-try-catch for Swift:

currentNavController - the UINavigationController inside which the SDK UI will be presented
challengeParameters - ACS details required by the 3DS SDK to conduct the challenge process during the transaction.
challengeStatusReceiver - a callback object for notifying the 3DS Requestor App about the challenge status.
timeOut - an interval, in minutes, within which the challenge process must be completed. The minimum possible value is 5 minutes. The recommended value for this parameter is 10 minutes..

Completing Authentication

There’re a couple of considerations for completing authentication. First, the authentication can be deemed successful if there was a corresponding transStatus received in ARes, the “Getting Authentication parameters” section above explains that.

Another possibility is to receive a call via ChallengeStatusReceiverinterface/delegate the app passed to doChallenge method. The interface methods are self-explanatory - completed etc.

It is also worth to make sure the code handles exceptional situations as there might be networking issues, device resources limited and so on and so forth.

Closing Transaction

When authentication completes, it is necessary for the application to close the transaction. There’s a closemethod in uSDK for that.

Note the CloseTransactionSpec instance is passed into the method. By default a new default instance would be just fine. If however there were SCA methods leveraged in the transaction then the CloseTransactionSpec instance needs to be specifically prepared. The SCA methods are documented in another section of this document.

Android

The method is called like this:

iOS

The corresponding iOS method signature is this: