- Project Overview
- Usage
- Before You Start: Getting MTLS Client Certificates for Your Project
- Build and Execute
- API Reference
- About This Project
- Support
- License
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.
- Java 8 or later
- 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_HOMEenvironment variable to match the location of your Java installation.
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.
There are two different types of MTLS client certificates, depending on the stage of your project:
- Sandbox MTLS certificates, which give access to an API sandbox that mimics a live Production environment (mtf.api.mastercard.net)
- Production MLTS certificates, which allow an application to access the Production environment (api.mastercard.net) Domain/Server URL may vary depending on the API. Please check the API Reference section of the service documentation for the correct server URL.
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.
Visit the Mastercard Transaction APIs for Acquirers Tutorials & Guides for a step-by-step guide on requesting an MTLS 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:
- Format PKCS #8
- 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.
With the PKCS12 file downloaded from KMP, configure the properties for your client application as explained below -
-
Open
${project.basedir}/src/main/resources/application.propertiesand 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
- 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
.p12using the following command (provide input where necessary).
keytool -importkeystore -srckeystore <jks-file-location> \
-destkeystore <pkcs12-file-location> \
-srcstoretype JKS \
-deststoretype PKCS12 \
-deststorepass <keystore-password>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.api.mastercard.net/transaction-api ***
See also:
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.
This project was created using the OpenAPI Generator for generating API client and SDK libraries, server stubs, documentation and configuration.
The OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.
If you would like further information, please send an email to [email protected].
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.