Link Search Menu Expand Document
Table of contents
  1. Browser uSDK v6.5
    1. How uSDK is delivered
    2. License Key
    3. Using the uSDK
      1. Create an instance of the uSDK
      2. Initialize the uSDK
      3. Authenticate
    4. The authenticate method
      1. The authSpec parameter
      2. The authCallbacks parameter
    5. Advanced
      1. Dual-branded cards support
        1. The directory server choosing prompt

Browser uSDK v6.5

The uSDK 6.5 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 provides a uMPI plugin that handles most of the underlying work a merchant backend needs to do.

How uSDK is delivered

The uSDK can be downloaded from this page 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://some-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:

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

#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:

usdk.authenticate(authSpec, authCallbacks);

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. These classes are explained in details further in this document.

The authenticate method

The following diagram shows the complete set of actors and messages they perform during a normal 3DS transaction:

The authSpec parameter

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

class AuthSpec {
  
  // Card identifier. It should not be the card number but rather a unique
  // thing that identifies a card in the user's wallet.
  // Required.
  private cardID: string;
  
  // This is an arbitrary object that uSDK will convey as it is to the 
  // Merchant Backend. It is the recommended place to put purhcase related
  // information in, such as the purchase amount, the line items, etc.
  // Required.
  private purchaseInfo: any;
  
  // Is this a payment authentication? 
  //   TRUE  - payment 
  //   FALSE - non-payment (adding a card to the wallet for instance) 
  private isPaymentAuthentication: boolean;
  
  // An URL the ACS notifies requestor about the completion of 3DS Method
  // Optional, may be missed if no 3DS method needed
  private threeDsMethodNotificationURL: string;
  
  // An URL the ACS notifies the requestor about the completion of a 3DS challenge
  // Optional, may be missed if merchant does not want the uSDK to perform 
  // challenges.
  private notificatonURL: string;
    
  // An URL where the uSDK sends a supported-versions request to get the DS 
  // for the transaction.
  // Required.
  private supportedVersionsURL: string;
  
  // An URL where the uSDK sends a authentication data to
  // Required.
  private authURL: string;
  
  // If the requestor backend (Gateway) requires user authorization, 
  // then here the app passes the HTTP Headers that uSDK will include 
  // when sending requests to the four URLs above.
  // Optional. An empty map is assumed if not passed.
  private authorizationHeaders: Map<string, string>;
  
  // A reference to an iframe element that uSDK will use to display challenges.
  // The recommended workflow is this:
  // 1. The application creates an iFrame element and makes it invisible initially
  // 2. If the transaction requires a challenge, then uSDK calls 
  //    `challengeFlowStarted` callback to let the application make 
  //.   the iFrame visible
  // 3. After challenge flow is completed but before the transaction ends, 
  //    the uSDK calls back via the 'challengeFlowCompleted' callback so 
  //    the app can dispose the iFrame at that point
  private challengeIframe: HTMLIFrameElement;
}

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:

interface AuthCallbacks {
  
  // called when the transaction completed successfully - transStatus is Y, A, I
  authenticated(transactionId: string, transStatus: string);
  
  // called when the transaction NOT completed successfully - transStatus is N, U, R etc
  notAuthenticated(threeDSServerTransId: string, transStatus: string);
  
  // If decoupled auth (transStatus=D), 
  // then the result will be known latter. So the app should check on server for results later.
  decoupledAuthBeingPerforming(threeDSServerTransId: string, cardholderInfo: string | CardholderInfo);
  
  // User cancels the challenge
  cancelled(transactionId: string);
  
  // Error case
  // This would also be called if a non 200 response received from supported versions / auth endpoints
  error(threeDSServerTransId: string, e: Error);
  
  // Called before challenge flow begins. 
  // The app should make the challenge iframe visible at this moment
  challengeFlowStarted(threeDSServerTransId: string);
  
  // Called when challenge flow is completed but before 
  // authenticated/notAuthenticated/decoupledAuthBeingPerforming callbacks called. 
  // The app should dispose the challenge iframe at this point
  challengeFlowCompleted(threeDSServerTransId: string);
}

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:

The SDK is bundled with the following directory servers:

DS Identifier (RID) Provider Name
A000000003 Visa
A000000004 Mastercard
A000000025 American Express
A000000065 JCB
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:

const usdk = new Usdk({
  licenseKey: "<the license key issued by the administrator>",
  logLevel: "INFO", // DEBUG | INFO | WARN | ERROR,
  directoryServers: [
    { 
      dsIdentifier: 'A0000000XX',
      providerName: 'Some card brand', 
      logo: { type: 'svg', source: '<svg.../>'} 
    }
  ]
});

So, to sum it up - 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.


Table of contents