Reference Implementation for Mastercard Transaction APIs for Acquirers

Table of Contents

• Project Overview
  • Compatibility
• Usage
  • Prerequisites
  • Security & Authentication
• Before You Start: Getting MTLS Client Certificates for Your Project
  • Client Certificates and Environments
  • Creating and Renewing Client Certificate
  • Step-by-Step Guide on Requesting a Certificate
  • Download the appropriate Client Certificate
  • Configuration
  • Working with JKS instead of PKCS12
• Build and Execute
• API Reference
• About This Project
  • Integrating with OpenAPI Generator
• Support
• License

Project Overview

This is a reference application to demonstrate how the Mastercard Transaction API for Acquirers can be used for the supported operations. Please see here for details on the API: Mastercard Developers. To call this API, a valid Client Certificate file must be acquired and access provisioned as explained later in this documentation.

Compatibility

• Java 8 or later

Usage

Prerequisites

• Mastercard Developers Account with access to the Mastercard Transaction API for Acquirers
• A text editor or IDE
• Spring Boot 2.7+
• Apache Maven 3.3+
• Set up the JAVA_HOME environment variable to match the location of your Java installation.

Security and Authentication

• Using MTLS to access Mastercard APIs

Before You Start: Getting MTLS Client Certificates for Your Project

The client authentication side of the MTLS protocol involves a client certificate, a public key and a private key, known as a key pair. To use the key pair with Mastercard APIs, you will need to perform the onboarding steps detailed here.

Client Certificates and Environments

There are two different types of MTLS client certificates, depending on the stage of your project:

1. Sandbox MTLS certificates, which give access to an API sandbox that mimics a live Production environment (mtf.asn.api.gateway.mastercard.com)
2. Production MLTS certificates, which allow an application to access the Production environment (asn.api.gateway.mastercard.com) Domain/Server URL may vary depending on the API. Please check the API Reference section of the service documentation for the correct server URL.

Creating and Renewing Client Certificate

The Key Management Portal (KMP) is an application available in Mastercard Connect. KMP is a self-service portal for Mastercard customers, which allows them to request and exchange keys and certificates with Mastercard.

The portal provides guided workflows to create and manage requests for key and certificate exchange, as well as an inventory of all PKI for Business Partners keys and certificates that have been exchanged between Mastercard and customers using KMP.

Access the Key Management Portal application on Mastercard Connect to obtain MTLS client certificates. You can access the user guide within the KMP application for instructions on how to use the application.

Step-by-Step Guide on Requesting a Certificate

Visit the Mastercard Transaction APIs for Acquirers Tutorials & Guides for a step-by-step guide on requesting an MTLS Certificate.

Download the appropriate Client Certificate

Once you are notified that your Certificate Request is signed, you can access the client certificate in KMP.

When accessing your certificate, you will see an option to download the certificate. Ensure that the following options are selected:

1. Format PKCS #8
2. Uncheck “Include Root Chain” The certificate will be available to download. Save it to a safe location so that it can be uploaded to your project in Mastercard Developers or used within your client's run command.

Configuration

With the PKCS12 file downloaded from KMP, configure the properties for your client application as explained below -

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

  The below properties will be required for authentication of API calls.

  transaction-api.ssl.key-store, this refers to the .p12 file with the signing key. Please place the .p12 file in the project folder and update this property with the name of the file. If the key file is not present, you will receive this error:

  java.io.FileNotFoundException: key.p12 (No such file or directory)

  transaction-api.ssl.key-store-type, for .p12 files, this is "PKCS12" (without quotes)

  transaction-api.ssl.key-store-password, this is the password for the .p12 file. If it is modified, use what was identified when creating CSR on KMP

Working with JKS instead of PKCS12

• If you received a different format of key file, change the property transaction-api.ssl.key-store-type accordingly. For example, provide transaction-api.ssl.key-store-type=JKS if you received the JKS file.
• Alternatively you can convert that to .p12 using the following command (provide input where necessary).

keytool -importkeystore -srckeystore <jks-file-location> \
-destkeystore <pkcs12-file-location> \
-srcstoretype JKS \
-deststoretype PKCS12 \
-deststorepass <keystore-password>

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 then run the following command to start the project:

java -jar target/transaction-api-reference-application-2.0.0.jar

*** Note: the default environment is - https://mtf.asn.api.gateway.mastercard.com/transaction-api ***

See also:

• OpenAPI Generator (Plugin for Maven)
• OpenAPI Generator (executable)
• CONFIG OPTIONS for Java

API Reference

Please consult the API documentation at the API Reference page.

The OpenAPI specification file is also included in the project as ${project.basedir}/src/main/resources/transaction-api-openapi.yaml.

Note that the sample requests included in this project are for demo purposes only. Please modify for your use cases and change to valid values before running this application.

About this Project

This project was created using the OpenAPI Generator for generating API client and SDK libraries, server stubs, documentation and configuration.

Integrating with the OpenAPI Generator

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

Support

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

License

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