uMPI 3.0 docs

1 Overview
- 1.1 Prerequisites
- 1.2 How uMPI is delivered
2 Using the uMPI
- 2.1 Instantiation
- 2.2 GetSupportedVersions
- 2.3 Authenticate
- 2.4 GetTransactionStatus
3 Logging
4 Javadocs
5 The complete example

Overview

The uMPI plugin acts as a bridge between the 3DS requestor environment and the 3DS server. Typically the plugin is to be integrated with 3DS requestor’s backend (assuming it is written in Java 8+) enabling the latter to call its methods that would efficiently bridge them to the 3DS server and back.

The uMPI provides three primary methods for 3DS flows:

getSupportedVersions(GetSupportedVersionsParameters) for getting a list of Directory Servers for given account number
authenticate(AuthenticationParameters) for completing the 3DS authentication
getTransactionStatus(String) for getting transaction status

Prerequisites

Java 8+ environment
Understanding of gradle and/or maven tools.
A basic understanding of the 3-D Secure Protocol and Core Functions Specification is recommended.

How uMPI is delivered

The uMPI is shipped as a JAR (Java archive) file. It can be downloaded from the https://msignia.atlassian.net/wiki/spaces/UR/pages/782204952 page. Once downloaded, it is usually placed in the lib folder and then referred to in build.properties file:

dependencies {
  implementation('com.msignia.threeds:msignia-3ds-mpi:3.0.XX')
  
  // if placed in a `lib` folder, the following dependencies may be needed:
  implementation('com.google.code.gson:gson:2.8.0')
  implementation('org.apache.httpcomponents:httpclient:4.5.6')
  implementation('org.springframework:spring-web')
  implementation('com.baidu.unbiz:fluent-validator:1.0.9') {
      exclude group: 'org.slf4j', module: 'slf4j-log4j12'
  }
  implementation('org.hibernate:hibernate-validator:5.3.5.Final')
  implementation('org.glassfish:javax.el:3.0.0')
  implementation('commons-validator:commons-validator:1.6')
  implementation('com.nimbusds:nimbus-jose-jwt:5.8')
}

mSIGNIA also hosts a private Maven repository with the uMPI. If that method of getting uMPI and its dependencies is preferred, then contact the mSIGNIA administrator for more information.

Using the uMPI

Instantiation

Here is an example of instantiating the MPI.

ThreeDsMerchantPlugin plugin = new PluginImpl.Builder()
   .threeDsServerUrl("https://3ds.msignia.com")
   .supportedVersionsEndpoint("/api/v2/supportedVersions")
   .authenticationEndpoint("/api/v2/authenticate")
   // TLS parameters for mutual auth between the Merchant and 3DS-Server
   .tlsParameters(buildTlsParams()) 
   .build()

Once the instantiation is done, the plugin variable holds a reference to the main entity of the plugin that exposes the methods to the 3DS requestor backend to consume. The methods are described in the next sections.

GetSupportedVersions

The method gets one or more Directory Server for a given account number:

GetSupportedVersionsParameters params = new GetSupportedVersionsParameters();
params.setAcctNumber("... card number ...");
params.setThreeDSRequestorID("... 3DS Requestor ID...");
params.setEmail("... User email...");

try {
    GetSupportedVersionsResponse response = plugin.getSupportedVersions(params);
    
    if (response.size() > 0) {
    	SupportedVersionsByDsResponse.Item ds = response.get(0);
    	logger.debug("threeDSServerTransID", ds.getThreeDSServerTransID());
    	logger.debug("threeDSMethodURL", ds.getThreeDSMethodURL());
    	logger.debug("dsIdentifier", ds.getDsIdentifier()));
    	logger.debug("acsStartProtocolVersion", ds.getAcsStartProtocolVersion());
    	logger.debug("acsEndProtocolVersion", ds.getAcsEndProtocolVersion());
    	logger.debug("dsStartProtocolVersion", ds.getDsStartProtocolVersion());
    	logger.debug("dsEndProtocolVersion", ds.getDsEndProtocolVersion());    	
    }
}
// GetSupportedVersionsResponse were not valid, inspect the validation errors like below:
catch (InvalidInputException ie) {
    for(InvalidInputException.InputError error : ie.getErrors()) {
        logger.debug("Invalid input: field: {}, errorCode: {}, message: {}, invalidValue: {}",
            error.getField(), error.getCode(), error.getMessage(), error.getInvalidValue());
    }
}
catch (ThreeDsMerchantPluginException e) {
    logger.error("General plugin exception!", e);
}

This method is synchronous, so it is the caller’s responsibility to fork a thread for it if appropriate.

Authenticate

The Authenticate method is used by 3DS requestor environment to kick off the 3DS Authentication Flow. This typically occurs when the user submits a purchase order to the merchant backend. At that moment, the backend calls the authenticate method which validates the parameters and conveys them to the 3DS Server. The 3DS Server then performs the EMV 3-D Secure Authentication routine and returns back an ARes or Erro message to the requestor backend to inspect and proceed further with the Authentication Flow.

It returns an instance of AuthenticationResponse which contains the contents of an ARes or Erro. An additional field to be aware of is `encodedCreq`. This field may be returned in the `ARes` on Browser challenge flows and is a base64 encoded CReq message that should be passed back to the browser upon a transStatus of C.

It is recommended to check 3DS specification for possible transaction statuses in an ARes instead of relying solely on the example above.

GetTransactionStatus

The method gets transaction data from 3DS Server by given transaction ID. It returns an instance of TransactionStatusResponse which is a holder for the authenticationValue, eci and dsTransID:

Logging

The plugin leverages SLF4J for logging which means the 3DS merchant application might use it with any popular logging framework such as java.util.logging, logback, log4j.

Javadocs

For more detailed information about the class structure and fields refer to javadocs for the uMPI.

The complete example

mSIGNIA provides the complete sample application that shows how uMPI can be integrated into a merchant backend.