Mastercard Processing APMEA Issuing APIs - Reference Application

Table of Contents

• Overview
• Pre-requisites
  • Mastercard Account
  • Certificates/Keys
  • Softwares/Libraries
• Usage
  • Step 1 - Clone git project
  • Step 2 (Optional) - Copy latest API Specs
  • Step 3 - Certificates Configuration
    • 3.1 Download & install certificates
    • 3.2 mTLS Certificate configuration
    • 3.3 PIN block Encryption Certificate configuration
    • 3.4 Data Encryption Certificate configuration
      • 3.4.1 Option 1 (Recommended) - Different AES key for request & response
      • 3.4.2 Option 2 - Common AES key for request & response
  • Step 4 (Optional) - Generating The API Client Sources & Review
  • Step 5 - Build the project
  • Step 6 - Execute the Use-Cases
• Execute the Use-Cases
• Use-Cases
• API Reference
  • OpenAPI Specs
  • API Client Helper
    • API Client
    • SSL Context for mTLS
    • PIN block formation and encryption
    • Data Encryption and Decryption
    • Request/Response Logging
  • Other References
• Support
• License

---

Overview

Mastercard Processing APMEA Issuing Digital First provides card processing platform to deliver a secure and seamless customer experience for prepaid, debit, and credit products.

Mastercard Processing APMEA Issuing platform enables:

• instantly issue physical or digital primary, add-on, and supplementary prepaid cards from anywhere, anytime
• handling card profile activities
• manage and control all card activities seamlessly
• safe and secure solution to handle all PIN-related activities for cards
• processing all card transaction activities

This is a reference application to demonstrate how Mastercard Processing APMEA Issuing Digital First APIs can be consumed. Issuing Digital First APIs support prepaid, debit, and credit cards processing.

This Reference application is a guide for using Issuing APIs for cards processing. Please visit Mastercard Developer portal for more details about the APIs: Mastercard Developers.

---

Pre-requisites

1. Mastercard Account

• Mastercard Developers portal account

2. Certificates/Keys

• mTLS Client Certificate: Customers need to use the Key Management Portal (KMP) hosted on Mastercard Connect to provision MTLS client certificates. Contact: KMD team to onboard.

mTLS Certificate Approval - Create a new project on Mastercard Developers and add MI Issuing APIs to it and upload the mTLS certificate and click continue and wait for on-boarding & approval.

• RSA Public Key/Certificate for Data Encryption - Customers need to request certificates/keys for PIN encryption and API request encryption using above process.

• RSA Private Key/Certificate for Data Decryption - Customers need to generate RSA key pair and share public key with Mastercard.

Note: Sandbox APIs are instantly accessible without following the above process to get certificates/keys from Mastercard Key Management team. Required certificates/keys are available on Mastercard Developers Portal for Sandbox environment (simulates the production environment with dummy data).

3. Softwares/Libraries

• Java 8 or later
• Apache Maven 3.3+
• OpenAPI Generator
• A text Editor or any IDE (We will refer to IntelliJ IDEA for this guide) with Lombok plugins

Note: Set up the JAVA_HOME environment variable to match the location of your Java installation.

---

Usage

Step 1 - Clone git project

Clone the project from GitHub -

git clone https://github.com/Mastercard/issuing-api-reference-app.git

Step 2 (Optional) - Copy latest API Specs

• Download the latest API specs from Mastercard Developer portal, if required.
• Copy these specifications in reference application source code - src\main\resources\yaml_specs

Step 3 - Certificates Configuration

Let's assume that you wish to configure and test Mastercard Issuing API available in sandbox environment.

Note: You may create a environment specific folder like (src\main\resources\mtf) or (src\main\resources\prod) and do similar configurations and pass the JVM argument env like -Denv=mtf while executing the code so that all configurations can be picked from this environment specific folder.

**3.1 Download & install certificates

Download & install the mTLS certificate** and encryption certificate and configure the paths & credentials in application.properties file in reference application source code (src/main/resources/sandbox).

3.2 mTLS Certificate configuration:

Configurations in src/main/resources/sandbox/application.properties

Property Name	Description
mi.api.mtls.keystore.file	Path to mTLS certificate keystore (PKCS #12, including chain) .pfx file
mi.api.mtls.keystore.password	Password of the Keystore that contains the mTLS certificate referred above file.

Note: Here, reference application makes use of keystore file for the purpose of demo. But it is recommended to store your private certificate/key in physical devices such as USB Tokens, Smart Cards, or Hardware Storage Module (HSM) and write your own code to extract the certificate from your device rather than fetching it from keystore.

3.3 PIN block Encryption Certificate configuration:

Configurations in src/main/resources/sandbox/application.properties

Property Name	Description
mi.api.pin.encryption.tdea.public.key.file	Path to card PIN block (ISO Format 0) encryption certificate keystore (PKCS #8, excluding chain) file that contains Mastercard RSA Public key .cer file

3.4 Data Encryption Certificate configuration:

3.4.1 Option 1 (Recommended) - Different AES key for request & response - Mastercard & Client both sharing their Public Key

Configurations in src/main/resources/sandbox/application.properties

Property Name	Description
mi.api.encryption.public.key.file	Path to data encryption certificate keystore (PKCS #8, excluding chain) file that contains Mastercard RSA Public key .cer file
mi.api.encryption.public.key.fingerprint	The hex-encoded SHA-256 digest of Mastercard RSA public key referred above
mi.api.encryption.oaep.algorithm	OAEP (Optimal Asymmetric Encryption Padding) padding digest algorithm used together with RSA encryption. For example, SHA256, SHA512, NONE
mi.api.encryption.private.key.keystore.file	Path to data decryption certificate keystore (PKCS #12, excluding chain) file that contains your RSA Private key .cer file. Ideally it should be retrieved from hardware device
mi.api.encryption.private.key.keystore.password	Password of the Keystore that contains the data decryption Private Key referred above file.

3.4.2 Option 2 - Common AES key for request & response - only Mastercard shares their Public Key

Configurations in src/main/resources/sandbox/application.properties

Property Name	Description
mi.api.encryption.public.key.file	Path to data encryption certificate keystore (PKCS #8, excluding chain) file that contains Mastercard RSA Public key .cer file
mi.api.encryption.public.key.fingerprint	The hex-encoded SHA-256 digest of Mastercard RSA public key referred above
mi.api.encryption.oaep.algorithm	OAEP (Optimal Asymmetric Encryption Padding) padding digest algorithm used together with RSA encryption. For example, SHA256, SHA512, NONE

Note: Please refer to the sample values provided in reference application properties file.

Step 4 (Optional) - Generating The API Client Sources & Review

Now that you have all the dependencies you need, you can generate the sources. We have already integrated OpenAPI Generator Maven Plugin as well as OpenAPI Specs of all the API in the pom.xml which generates API client libraries using configured OpenAPI Specs. OpenAPI Generator provides generators and library templates for supporting multiple languages and frameworks.

If you don't wish to review the generated code or API client reference code then you may skip this step since next step - Build covers the generation of client source as well.

To generate the code, use one of the following two methods:

Option 1 - Using Terminal

Navigate to the root directory of the project within a terminal window and execute below command:

mvn clean compile

Option 2 - Using IDE

• Ensure that Lombok plugins is installed
• 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.

Step 5 - Build the project

Once you have updated the certificates & properties, you are ready to build the application. You can do this by navigating to the project's base directory from the terminal and then by running the following command.

mvn clean install -Dmaven.test.skip=true

Step 6 - Execute the Use-Cases

When the project builds successfully, you can run the following command to start/run the Spring Boot application:

java -Denv=sandbox -jar target/issuing-api-reference-app-1.0.3.jar  

Note: Checkout the API response in the output_<env> folder (relative path).

• Add argument search-cards or get-card in above command to execute/test each API individually. For example,

• Run below command to execute/test the Search Cards ( /card-management/cards/searches) API

java -Denv=sandbox -jar target/issuing-api-reference-app-1.0.3.jar search-cards

• Run below command to execute/test multiple APIs like Search Cards ( /card-management/cards/searches) API and Get Card (/card-management/cards/{card_id}) API

java -Denv=sandbox -jar target/issuing-api-reference-app-1.0.3.jar search-cards get-card

• Run below command to find the complete list of use cases available in reference-app for testing

java -Denv=sandbox -jar target/issuing-api-reference-app-1.0.3.jar list

• Run below command to execute/test all the use cases available in reference-app for testing

java -Denv=sandbox -jar target/issuing-api-reference-app-1.0.3.jar all

NOTE:
- For MTF & PROD environment, update request with valid details in JSON files under location /src/main/resources/<env>/sample_requests/ in order to execute these apis successfully.

---

Service Use-Cases Documentation

Latest Open API use-cases documentation can be found here:

• Card Issuance Use Cases
• Card Management Use Cases
• Card Controls Use Cases
• Authorization Management Use Cases
• Transaction Management Use Cases (coming soon...)

---

API Reference

OpenAPI Specs

Latest Open API specifications can be found here:

• Card Issuance API Specs
• Card Management API Specs
• Card Controls API Specs
• Authorization Management API Specs
• Transaction Management API Specs (coming soon...)

To develop a client application that consumes a Issuing RESTful APIs with Spring Boot.

API Client Helper

The com.mastercard.developer.issuing.client.helper.ApiClientHelper class assists you with all the prerequisites for calling Issuing APIs. It covers all the below mentioned points:

#### API Client It is recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues. You can use the `getApiClient` static method of `ApiClientHelper` class to create new instance of `ApiClient` and initialize all the required configurations.

SSL Context for mTLS

The ApiClientHelper class also helps in setting up SSLContext based on the configurations provided in the application.properties file and set to OkHttpClient.Builder instance. OkHttpClient.Builder instances are cached for each service (unique URI).

PIN block formation and encryption

The com.mastercard.developer.issuing.client.helper.PinBlockTDEAEncrypter is a singleton class that you can use when to encrypt card PIN. It consists of PIN block formation and encryption process.

Data Encryption and Decryption

The com.mastercard.developer.interceptors provides OkHttpFieldLevelEncryptionInterceptor and OkHttpGetRequestEncryptionHeaderInterceptor 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.

Request/Response Logging

The com.mastercard.developer.interceptors.OkHttpLoggingInterceptor class provides you the request and response logging functionality for debugging purpose. The request/response may contain sensitive data, hence this logging must be disabled by simply changing the mi.client.debug.mode property value to false in application.properties file.

### Other References - [OpenAPI Generator (Maven Plugin)](https://openapi-generator.tech/docs/plugins/)

---

Support

If you would like further information, please send an email to apisupport@mastercard.com

---

License

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