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.
- Java 11 or later
- 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.
-
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 keystoresi.auth.keystore-type
: The type to your keystore. Ex:keyStore-type: pkcs12
app.encryption.enabled
: Set to true if you want to encrypt theacctNumber
field and want to run the related scenario, false otherwiseapp.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
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
<!-- 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
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 iconsReimport All Maven Projects
andGenerate Sources and Update Folders for All Projects
-
Method 2
In the same menu, navigate to the commands ({Project name} > Lifecycle), selectclean
andcompile
then click the iconRun Maven Build
.
Using Terminal
- Navigate to the root directory of the project within a terminal window and execute
mvn clean compile
command.
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
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
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.
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.
The API Reference can be found here
For more information, please refer to the Support Page
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.