3DS Smart Interface Reference Application

• Overview
  • Compatibility
• Usage
  • Prerequisites
  • Configuration
  • Integrating with OpenAPI Generator
    • OpenAPI Generator Plugin Configuration
    • Generating The API Client Sources
  • Build and Execute
• Use Cases
  • Frictionless Authentication
  • Challenge Authentication
• PAN Encryption
• API Reference
• Support
• License

Overview

3DS Smart Interface provides a suite of APIs to the 3DS Requestors to facilitate 3D Secure transactions. The list of available APIs for the Merchants/Requestors to integrate with are as below:

• AuthenticationApi

• SupportedVersionsApi

This reference application helps to demo to the Merchants/Requestor on how they can integrate their backend service to connect to the 3DS Smart Interface APIs to enable 3DS transactions under different use cases.

Compatibility

• Java 11 or later

Usage

Prerequisites

• Mastercard Developers Account with access to Mastercard 3DS Smart Interface API
• A text editor or IDE
• Spring Boot 2.2+
• Apache Maven 3.3+
• Set up the JAVA_HOME environment variable to match the location of your Java installation.

Configuration

• Create an account at Mastercard Developers.

• Request access to 3DS Smart Interface

• Generate a key by following the procedure for Getting Access

• Copy your .jks or .p12 keystore into ${project.basedir}/src/main/resources/security

• Copy your .crt encryption certificate into ${project.basedir}/src/main/resources/encryption

• Open ${project.basedir}/src/main/resources/application.properties and configure below parameters.

• Update the following keys in application.yml file.

  • si.auth.keystore: Path where you saved your keystore. Ex: /security/your-keystore.p12
  • si.auth.keystore-password: The password to your keystore
  • si.auth.keystore-type: The type to your keystore. Ex: keyStore-type: pkcs12
  • app.encryption.enabled: Set to true if you want to encrypt the acctNumber field and want to run the related scenario, false otherwise
  • app.encryption.cert: Path where you saved the cert used for PAN Encryption. Ex: /encryption/your-encryption-cert.crt

• Example:

si:
  base-path: 
  auth:
    keyStore: /security/your-keystore.p12
    keyStore-password: yourPassword 	
    keyStore-type: pkcs12 	

app:
  encryption:
    cert: /encryption/your-encryption-cert.crt
    enabled: true

Integrating with OpenAPI Generator

OpenAPI Generator generates API client libraries from OpenAPI Specs. OpenAPI generator is used to create the API client library (in target folder by default) and is used as dependency by the application for making requests to the MC service.

See also:

• Generating and Configuring a Mastercard API Client
• OpenAPI Generator (maven Plugin)
• OpenAPI Generator (executable)
• CONFIG OPTIONS for java

OpenAPI Generator Plugin Configuration

<!-- https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin -->
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapitools.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/reference-service.yaml</inputSpec>
                <generatorName>java</generatorName>
                <apiPackage>com.mastercard.api</apiPackage>
                <modelPackage>com.mastercard.api.model</modelPackage>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <generateModelDocumentation>false</generateModelDocumentation>
                <generateApiDocumentation>false</generateApiDocumentation>
                <skipValidateSpec>false</skipValidateSpec>
                <typeMappings>
                    <typeMapping>OffsetDateTime=String</typeMapping>
                    <typeMapping>LocalDate=String</typeMapping>
                </typeMappings>
                <importMappings>
                    <importMapping>java.time.OffsetDateTime=java.lang.String</importMapping>
                    <importMapping>java.time.LocalDate=java.lang.String</importMapping>
                </importMappings>

                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                    <supportingFiles>false</supportingFiles>
                    <dateLibrary>java8</dateLibrary>
                    <verbose>true</verbose>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

For more information on how this client generator works please consult the official Github repository

Generating the API Client Sources

Now that you have all the dependencies you need, you can generate the sources. To do this, use one of the following two methods:

Using IDE

• Method 1
  In IntelliJ IDEA, open the Maven window (View > Tool Windows > Maven). Click the icons Reimport All Maven Projects and Generate Sources and Update Folders for All Projects

• Method 2
  In the same menu, navigate to the commands ({Project name} > Lifecycle), select clean and compile then click the icon Run Maven Build.

Using Terminal

• Navigate to the root directory of the project within a terminal window and execute mvn clean compile command.

Build and Execute

Once you’ve added the correct properties, we can build the application. We can do this by navigating to the project’s base directory from the terminal and running the following command

mvn clean install

When the project builds successfully, you can run the following command to start the project

java -jar target/smart-interface-reference-1.0.0.jar

Use Cases

Frictionless Authentication

Frictionless authentication occurs when a submitted request does not require an Additional Factor of Authentication (AFA) as deemed by either an Issuer ACS, a Directory Server (DS) Authentication service, or by a country or regional regulatory requirement.

Frictionless authentication involves the SupportedVersions and Authentication APIs.

Frictionless Authentication - Browser

Frictionless Authentication - Mobile App

Challenge Authentication

If the ACS determines that any further cardholder interaction is required to complete the authentication, the Frictionless Flow transitions into the Challenge Flow. The requestor decides whether to proceed with the challenge or terminate the 3-D Secure authentication process.

Challenge authentication involves the SupportedVersions and Authentication APIs.

Challenge Authentication - Browser

Challenge Authentication - Mobile App

Decoupled Authentication is a method whereby the authentication can occur independently from the cardholder’s experience with the 3DS Requestor.

This type of authentication usually involves special consideration from other challenge flows for the timing of results.

Decoupled Authentication

PAN Encryption

To submit an encrypted PAN, the requestor must:

Support RSA-OAEP-256 based algorithm for JWE encryption. Pair with any of the below AES algorithms for symmetric encryption:

• A128CBC-HS256
• A128GCM

Ensure that the generated JWE protected header of the encrypted payload includes the key identifier (KID) of the public key that is being used to perform the encryption. We recommend using the SHA1 Thumbprint of the downloaded public key certificate to be used in the “kid” field.

A sample JWE Protected Header element might look like this.

{
  "alg": "RSA-OAEP-256",
  "enc": "A128GCM",
  "kid": "8DB2A39BF250AC2761FF4C2F2FAACB7B3DC93416"
}

Add encrypted PAN to the Authentications or Supported Versions API – Data Element encryptedData.

API Reference

The API Reference can be found here

Support

For more information, please refer to the Support Page

License

Copyright 2021 Mastercard

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.