Reference Implementation for Mastercard Promotions Digital Enablement

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Configuration
  • Integrating with OpenAPI Generator
  • Build and Execute
• Use Cases
• API Reference
  • Authorization
  • Encryption and Decryption
    • Loading Encryption Certificate
    • Loading Decryption Key
    • Configuring JWE Instance
    • Encrypting Entire Payloads
    • Decrypting Entire Payloads
  • Request Examples
  • Recommendation
• Support
• License

Overview

This is a reference application to demonstrate how Promotion Digital Enablement API can be used for the supported operations. Please see here for details on the API: Mastercard Developers. This application illustrates connecting to the Promotion Digital Enablement API with encryption. To call these APIs, consumer key, .p12 files and encryption certs are required from your Mastercard Developers project.

Compatibility

• Java 8 or later

References

• Mastercard’s OAuth Signer library
• Using OAuth 1.0a to Access Mastercard APIs

Usage

Prerequisites

• Mastercard Developers Account with access to Promotion Digital Enablement 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.

• Create a new project and add Promotion Digital Enablement API to your project.

• Configure project and download signing key. It will download the zip file.

• Select .p12 files from zip and copy it to src/main/resources in the project folder.

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

  mastercard.api.base-path=https://sandbox.api.mastercard.com/loyalty/rewards, its a static field, will be used as a host to make API calls.

  Below properties will be required for authentication of API calls.

  mastercard.api.key-file=, this refers to .p12 file found in the signing key. Please place .p12 file at src\main\resources in the project folder and add classpath for .p12 file.

  mastercard.api.consumer-key=, this refers to your consumer key. Copy it from "Keys" section on your project page in Mastercard Developers

  mastercard.api.keystore-alias=keyalias, this is the default value of key alias. If it is modified, use the updated one from keys section in Mastercard Developers.

  mastercard.api.keystore-password=keystorepassword, this is the default value of key alias. If it is modified, use the updated one from keys section in Mastercard Developers.

  Below properties will be required to encrypt and decrypt the request and response payloads

  mastercard.api.encryption-certificate-file=, this is the path to certificate (.crt or .pem) file. Add classpath for file, after placing it at src\main\resources in the project folder. Download Encryption Key from "Client Encryption" section on your project page in Mastercard Developers

  mastercard.api.decryption-key-file=, this is your private key (.p12) file, required to decrypt a request. Add classpath for this file, after placing it at src\main\resources in the project folder.

  mastercard.api.decryption-key-alias=, this is required to load your decryption private key.

  mastercard.api.decryption-keystore-password=, this is required to load your decryption private key.

Integrating with OpenAPI Generator

OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.

See also:

• 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>${openapi-generator.version}</version>
    <executions>
        <execution>
            <id>Promotions Digital Enablement API Client</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/Promotions_Digital_Enablement-api-spec.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

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 ./mvnw 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

1. Run mvn clean install from the root of the project directory.
2. Run mvn spring-boot:run to start the project.
3. Navigate to http://localhost:8080/swagger-ui/index.html in your browser.

Swagger

Navigate to http://localhost:8080/swagger-ui/index.html in your browser to access bellow controllers,

1. AccountController
   1. /accounts/searches
2. OptInController
   1. /promotion-activations
   2. /promotions
3. ProgressController
   1. /promotion-progresses

Use Cases

Refer Use Cases for more details.

API Reference

Refer Api Reference To develop a client application that consumes a RESTful Promotion Digital Enablement API with Spring Boot.

Authorization

The com.mastercard.developer.interceptors package will provide you with some request interceptor classes you can use when configuring your API client. These classes will take care of adding the correct Authorization header before sending the request.

Encryption and Decryption

The com.mastercard.developer.interceptors provides a class that you can use when configuring your API client. This class will take care of encrypting payload before sending the request and decrypting payload after receiving the response.

Loading Encryption Certificate

A Certificate object can be created from a file by calling EncryptionUtils.loadEncryptionCertificate:

Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate("<insert certificate file path>");

Supported certificate formats: PEM, DER.

Loading Decryption Key

From a PKCS#12 Key Store

A PrivateKey object can be created from a PKCS#12 key store by calling EncryptionUtils.loadDecryptionKey the following way:

PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(
                                    "<insert PKCS#12 key file path>", 
                                    "<insert key alias>", 
                                    "<insert key password>");

Configuring JWE Instance

Use the JweConfigBuilder to create JweConfig instances. Example:

JweConfig jweConfig = JweConfigBuilder.aJweEncryptionConfig()
        .withEncryptionCertificate(certificate)
        .withEncryptionPath("$", "$")
        .withEncryptedValueFieldName("encryptedPayload")
        .withDecryptionKey(decryptionKey)
        .build();

Encrypting Entire Payloads

Example using the configuration above:

String payload = "{" +
    "    \"sensitiveField1\": \"sensitiveValue1\"," +
    "    \"sensitiveField2\": \"sensitiveValue2\"" +
    "}";

Output:

{
    "encryptedPayload": "eyJhbGciOiJSU0EtT0(...)IsImVuYyI6IkEyNTifQ.OKOawDo13gRp2ojaHV7LFpZcg(...)VZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe.48V1_ALb6US04U3b.5eym8TW_c8SuK0ltJ3rpYI(...)7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji.XFBoMYUZodetZdvTiFvSkQ"
}

Decrypting Entire Payloads

Example using the configuration above:

String encryptedPayload = "{" +
    "  \"encryptedPayload\": \"eyHhbGciOiJSU0EtT0F(...)BiYzQyTIyNTQ1ODgzNSJ9.VkO7N6gAptqoD7IQaK(...)ptYySP_TuvERby89DY1EezAm3A.qj6ISyzq1ASDJKD0.ENF7bUfBkoWAEYvk(...)o9JGMctx-PSdeVqwCQAVRNj0pYs1WjOp4UDbE4eEZIF6YA.Wc7ARH7R6sikpKzxET3MYA\" +
    "}";

Output:

{
    "sensitiveField1": "sensitiveValue1",
    "sensitiveField2": "sensitiveValue2"
}

Recommendation

It is recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Support

If you would like further information, please send an email to [email protected]

License

Copyright 2020 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.