Browser uSDK 6.X 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 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 choosing prompt
5 The complete example

Overview

The uSDK 6.4 for Browser is a javascript 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 that, mSIGNIA provide 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 sample backend application code to help merchants to get started.

How uSDK is delivered

The uSDK can be downloaded from this page. Once downloaded, it has to be placed in a project and referenced in a <script> tag, just like any other javascript library is referenced.

<script src="https://merchant-backend.com/usdk.js"></script>

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 need to be done in order to have a 3DS transaction executed:

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 opens the web page, 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:

const usdk = new Usdk({
  licenseKey: "<the license key issued by the administrator>",
  logLevel: "INFO", // DEBUG | INFO | WARN | ERROR
});

Initialize the uSDK

Then it has to be initialized:

usdk.initialize().then(() => {
  console.log("uSDK initialized successfully!");
}).catch((error) => {
  console.log("uSDK failed to initialize, error: ", error);
});

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 authCallbacks object is what the uSDK calls back when a 3DS transaction completes.

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 Browser 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 web 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:

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, 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 choosing prompt

When the uSDK receives more than one Directory Server it displays a prompt for the user to make a selection. By default, the uSDK has the following Directory Server bundled:

DS Identifier	Provider Name

DS Identifier	Provider Name
A000000003	Visa International
A000000025	American Express
A000000004	Mastercard International
A000000152	Discover

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:

See the Browser Sample app for how to specify additional directory servers and logotypes for them.

For the best results, the width of the logotype image should be 200 pixels.

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.

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.