Android uSDK 6.4 docs

1 Overview
- 1.1 How uSDK is delivered
- 1.2 License Key
2 Using the uSDK
- 2.1 Create an instance of the uSDK
- 2.2 Initialize the uSDK
- 2.3 The initSpec parameter
- 2.4 The initCallback parameter
- 2.5 Authenticate
3 The authenticate method
- 3.1 The authSpec parameter
- 3.2 The authCallbacks parameter
4 Advanced
- 4.1 Dual-branded cards support
  - 4.1.1 The directory server user choice prompt
5 Javadocs
6 The complete example

Overview

The uSDK 6.4 for Android is an aar library that implements 3DS v2 specification. The library also has an authenticate public method that should be used as a single interface to complete a 3DS transaction. Calling the method lets the uSDK take over the complexities of 3DS method execution including challenge flows and handling dual-branded cards.

The uSDK expects the merchant backend to expose a couple of endpoints so the uSDK can call them behind the scenes. To help merchants with this mSIGNIA provides a uMPI plugin that handles most of the underlying work a merchant backend needs to do.

mSIGNIA provides documentation for the uMPI plugin as well as publishes the Android sample application code to help merchants get started.

How uSDK is delivered

The uSDK can be downloaded from this page.

License Key

mSIGNIA administrator will have provided the customer with a license key for the uSDK. The license key should be passed to the uSDK at initialization time as shown later in this document.

Using the uSDK

Once the uSDK is integrated, there are three actions required in order to execute a 3DS transaction:

Create an instance of the uSDK
Initialize the uSDK
Call the authenticate method on the uSDK and wait for it to call back with transaction result

Steps #1 and #2 can be done when the user launches the app, while #3 is usually deferred to the moment the user makes an actual purchase.

Create an instance of the uSDK

An instance of uSDK is created like this:

ThreeDS2Service threeDS2Service = new UsdkThreeDS2ServiceImpl()

Initialize the uSDK

Then it has to be initialized:

threeDS2Service.initialize(initSpec, initCallback);

The initSpec argument encloses the parameters the uSDK needs for initialization and the initCallback object is what the uSDK calls when an initialization process completes.

The `initSpec` parameter

The parameter encapsulates all the data the app passes to the uSDK in initialize method:

public class InitSpec {

    // The license key issued by the MSignia administrator
    private String licenseKey;
    
    // An instance of Android application context
    private Context applicationContext;
    
    // Sets a string that represents the locale for the app's user interface.
    // For example, the value of locale can be "en_US" in Java.
    // If this parameter is not provided, then the default device locale is used.
    private String locale;

    // Returns an UI configuration information that is used to specify
    // the UI layout and theme. For example, font style and font size.
    private UiCustomization uiCustomization;

    // A configuration information that shall be used during initialization.
    // For example ConfigParameters can be used for passing custom DirectoryServers.
    private ConfigParameters configParameters;
}

The `initCallback` parameter

This is an interface used by the uSDK to call the Android application when initialization method finishes:

Authenticate

And finally, when the user makes a purchase, the authenticate method is called:

The authSpec argument encloses the parameters the uSDK needs in order to perform a transaction and the authCallback object is what the uSDK calls back when a 3DS transaction completes.

Avoid parallel execution authenticate method because it may need interaction with user via UI.

The `authenticate` method

Before getting into the details of authenticate method, it is recommended to familiarize yourself with the overall integration approach recommended. See the Mobile Authenticate Flow.

The `authSpec` parameter

The parameter encapsulates all the data the app passes to the uSDK in authenticate method:

The `authCallbacks` parameter

This is an interface used by the uSDK to call the Android application back when transaction finishes, gets canceled by the user, or gets erred:

The following diagram explains the interface methods the uSDK calls and when it does that:

Advanced

Dual-branded cards support

As the sequence diagram above shows, 3DS Server may sometimes return more than one Directory Server from the supportedVersions call. At this point, the merchant may do one of the following:

It may hand the whole response back to the uSDK. In this case, the uSDK, seeing more than one Directory Server there, will prompt the user to pick one of them.
It may make the decision for the user on the backend. In this case, the backed reduces the number of Directory Servers to return to the uSDK to one. In that case, uSDK will use the one Directory Server for the transaction.

The directory server user choice prompt

When the uSDK receives more than one directory server, it will display a prompt where the user selects one of the directory servers. By default, the uSDK has the following Directory Servers bundled:

DS Identifier	Provider Name	Logotype

DS Identifier	Provider Name	Logotype
A000000003	Visa	An PNG image
A000000025	American Express	An PNG image
A000000004	Mastercard	An PNG image
A000000152	Discover	An PNG image
tbd	JCB	tbd

mSIGNIA is currently working with JCB team on getting the material bundled in the uSDK. Once the materials are set, the table above will be updated with the right RID/image info for JCB.

If some other Directory Server is received, the uSDK will fail to display the prompt because it does not have the provider name and the logotype configured for the DS. The application, however, can pass additional directory servers to the uSDK like this:

In summary, in some cases a 3DS Server may return more than one directory server for a transaction. In such a case, it should be narrowed to just one DS on the backed or let the uSDK prompt the user.

Javadocs

For more details on using uSDK, see the corresponding javadocs

The complete example

mSIGNIA provides the complete sample application that shows the uSDK integration as well as the details of authenticate method call. mSIGNIA also hosts a sample merchant backend as well as the complete 3DS environment with a 3DS Server, DS, and ACS to help the customers to integrate quickly and efficiently.