Merchant Identifier API Reference Application

Table of Contents

• Overview
  • Compatibility
  • References
  • Frameworks
• Setup
  • Prerequisites
  • Application Configuration
  • Build and Execute
  • Reference Application Usage
  • Integrating with OpenAPI Generator
• Use Cases
  • Parameters
  • Merchant Identifier
• API Reference
  • Reference App API Reference
  • Merchant Identifier API Reference
• Authentication
  • Mastercard's OAuth Library
• Support
• License

Overview

This project showcases retrieving merchant name and addresses using the Merchant Identifier API. This application illustrates connecting to the Merchant Identifier API using Mastercard's OAuth library, and an OpenAPI generated client.

Compatibility

• Java 11 or later

References

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

Frameworks

• OpenAPI Generator
• Java 11+
• Maven

Setup

Prerequisites

• Mastercard Developers Account
• A text editor or IDE
• Java 11+
• Apache Maven 3.3+
• Set up the JAVA_HOME environment variable to match the location of your Java installation.

Application Configuration

1. Follow this credentials quick guide to get the credentials needed to run this application
   • Be sure to add Merchant Identifier to your project.
   • A zip file will be downloaded automatically with your key.
2. Take note of the given consumer key, keyalias, and keystore password given upon the project creation.
3. Extract zip and place the .p12 file in /src/main/resources of the project.
4. Update the properties found in /src/main/resources/application.properties.

application.properties

mastercard.api.base-path=https://sandbox.api.mastercard.com/merchant-identifier, This is the URL that the application will use to connect to Mastercard. For production usage, just remove sandbox..

Below properties will be required for authentication of API calls.

mastercard.p12.path=, this refers to .p12 file found in the signing key. Place .p12 file at src\main\resources in the project folder then add the filename here. mastercard.consumer.key=, this refers to your consumer key. Copy it from "Keys" section on your project page in Mastercard Developers mastercard.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.keystore.pass=keystorepassword, this is the default value of key pass. If it is modified, use the updated one from keys section in Mastercard Developers.

Build and Execute

1. Run mvn clean install from the root of the project directory.
   • When install is run, the OpenAPI Generator plugin will generate the sources for connecting to the Merchant Identifier API.
2. run java -jar target/merchantidentifier-api-reference-app-X.X.X.jar to start the project.
   • Notice: Replace X with version of the reference app.
   • Example: java -jar target/merchantidentifier-api-reference-app-1.0.0.jar

Reference Application Usage

• Use the merchant identifier reference app by providing merchant descriptor to get the matches.
• click on a marker to open more information on the right panel.

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

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>4.3.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/merchant-identifier-api-spec.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <configurationFile>${project.basedir}/src/main/resources/openapi-config.json</configurationFile>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Use Cases

Parameters

These are the parameters used for the Merchant Identifier API.

Name	Type	Default Value	Purpose
merchant_descriptor	string	0	To find merchant list with identifier.
match_type	string	ExactMatch	To perform a type of the search for merchant identifiers
card_acceptor_id	string	-	To find merchant list matched by card acceptor id

Get information on a Merchant Identifier.

MerchantIdentfier API URL	Method	Parameters	Request Model	Response model
/merchants	GET	merchant_descriptor, match_type	string	merchant list with address and merchant descriptor
/merchants-by-card-acceptor-ids	GET	card_acceptor_id	string	merchant list with address and card acceptor id

API Reference

Reference Application API Reference

Reference App URL	Parameters	Reference App Usage	Merchant Identifier Endpoint Used
/merchant-identifier/merchants	merchant_descriptor, match_type	Search for merchant list with merchant identifier by match type	/merchant-identifier/merchants
/merchant-identifier/merchants-by-card-acceptor-ids	card_acceptor_id	Search for merchant list with card acceptor id	/merchant-identifier/merchants-by-card-acceptor-ids

Example Search Requests in a rest client of your choice:

• https://sandbox.api.mastercard.com/merchant-identifier/merchants?merchant_descriptor=DOLIUMPTYLTDWELSHPOOLWA&match_type=ExactMatch
• https://sandbox.api.mastercard.com/merchant-identifier/merchants?merchant_descriptor=DOLIUMPTYLTDWELSHPOOLWA&match_type=FuzzyMatch
• https://sandbox.api.mastercard.com/merchant-identifier/merchants-by-card-acceptor-ids?card_acceptor_id=C928456

Merchant Identifier API Reference

See the API Reference page in the documentation.

API Endpoint	Description
Merchant Identifier	Search for merchant list with matching merchant identifier

Authentication

Mastercard oauth1 Signer Library

This dependency is required to properly call the API.

<dependency>
    <groupId>com.mastercard.developer</groupId>
    <artifactId>oauth1-signer</artifactId>
    <version>1.2.3</version>
</dependency>

Link to the oauth1 library's Github

Looking for other languages?

See the code used in this application to utilize the library.

Found in /src/java/com.mastercard.midreferenceapplciation.config.ApiClientConfiguration

ApiClient client = new ApiClient();
HttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor(logger::info);
loggingInterceptor.level(HttpLoggingInterceptor.Level.BASIC);
try {
    client.setBasePath(basePath);
    client.setHttpClient(
            client.getHttpClient()
                    .newBuilder()
                    .addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, getSigningKey()))
                    .addInterceptor(loggingInterceptor)
                    .build()
    );

    return client;
} catch (Exception e) {
    logger.error("Error occurred while configuring ApiClient", e);
}
return client;

Support

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

License

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.

Copyright © 1994-2022, All Rights Reserved by Mastercard.