{"id":28577592,"url":"https://github.com/mastercard/merchant-identifier-reference-app","last_synced_at":"2025-06-11T00:38:58.830Z","repository":{"id":42564907,"uuid":"79433101","full_name":"Mastercard/merchant-identifier-reference-app","owner":"Mastercard","description":"Reference application for Merchant Identifier API","archived":false,"fork":false,"pushed_at":"2023-12-18T17:04:20.000Z","size":966,"stargazers_count":8,"open_issues_count":3,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-16T10:43:19.605Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mastercard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-01-19T08:38:23.000Z","updated_at":"2024-04-16T10:43:19.606Z","dependencies_parsed_at":"2023-12-18T17:45:17.497Z","dependency_job_id":"c3801532-b4cc-4e47-a779-d4d96644c943","html_url":"https://github.com/Mastercard/merchant-identifier-reference-app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fmerchant-identifier-reference-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fmerchant-identifier-reference-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fmerchant-identifier-reference-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fmerchant-identifier-reference-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/merchant-identifier-reference-app/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fmerchant-identifier-reference-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177339,"owners_count":22817349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-11T00:38:31.794Z","updated_at":"2025-06-11T00:38:58.809Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Merchant Identifier API Reference Application\r\n\r\n[![](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/Mastercard/loyalty-user-management-reference/blob/master/LICENSE)\r\n\r\n## Table of Contents\r\n\r\n- [Overview](#overview)\r\n    * [Compatibility](#compatibility)\r\n    * [References](#references)\r\n    * [Frameworks](#frameworks)\r\n- [Setup](#setup)\r\n    * [Prerequisites](#prerequisites)\r\n    * [Application Configuration](#configuration)\r\n    * [Build and Execute](#build-and-execute)\r\n    * [Reference Application Usage](#reference-application-usage)\r\n    * [Integrating with OpenAPI Generator](#integrating-with-openapi-generator)\r\n- [Use Cases](#use-cases)\r\n    * [Parameters](#parameters)\r\n    * [Merchant Identifier](#merchant-identifier)\r\n- [API Reference](#api-reference)\r\n    - [Reference App API Reference](#ref-app-api-reference)\r\n    - [Merchant Identifier API Reference](#merchant-identifier-api-reference)\r\n- [Authentication](#authentication)\r\n    * [Mastercard's OAuth Library](#oauth-library)\r\n- [Support](#support)\r\n- [License](#license)\r\n    \r\n\r\n## Overview \u003ca name=\"overview\"\u003e\u003c/a\u003e\r\nThis project showcases retrieving merchant name and addresses using the [Merchant Identifier API](https://developer.mastercard.com/merchant-identifier/documentation/api-reference/).\r\nThis application illustrates connecting to the Merchant Identifier API using Mastercard's OAuth library, and an OpenAPI generated client.\r\n\r\n### Compatibility \u003ca name=\"compatibility\"\u003e\u003c/a\u003e\r\n * [Java 11](https://www.oracle.com/java/technologies/javase-jdk15-downloads.html) or later\r\n \r\n### References \u003ca name=\"references\"\u003e\u003c/a\u003e\r\n* [Mastercard’s OAuth Signer library](https://github.com/Mastercard/oauth1-signer-java)\r\n* [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/using-oauth-1a-to-access-mastercard-apis/)\r\n\r\n## Frameworks \u003ca name=\"frameworks\"\u003e\u003c/a\u003e\r\n- OpenAPI Generator\r\n- [Java 11+](https://www.oracle.com/java/technologies/downloads)\r\n- [Maven](https://maven.apache.org/download.cgi)\r\n\r\n## Setup \u003ca name=\"frameworks-and-requirements\"\u003e\u003c/a\u003e\r\n\r\n### Prerequisites \u003ca name=\"prerequisites\"\u003e\u003c/a\u003e\r\n\r\n* [Mastercard Developers Account](https://developer.mastercard.com/dashboard)\r\n* A text editor or IDE\r\n* [Java 11+](https://www.oracle.com/java/technologies/downloads)\r\n* [Apache Maven 3.3+](https://maven.apache.org/download.cgi)\r\n* Set up the `JAVA_HOME` environment variable to match the location of your Java installation.\r\n\r\n### Application Configuration \u003ca name=\"configuration\"\u003e \u003c/a\u003e\r\n1. Follow this [credentials quick guide](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/quick-start-guide/) to get the credentials needed to run this application\r\n    - Be sure to add `Merchant Identifier` to your project.\r\n    - A zip file will be downloaded automatically with your key.\r\n2. Take note of the given **consumer key**, **keyalias**, and **keystore password** given upon the project creation.\r\n3. Extract zip and place the `.p12` file in `/src/main/resources` of the project.\r\n4. Update the properties found in `/src/main/resources/application.properties`.\r\n\r\n#### application.properties\r\n\r\n`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.`.\r\n    \r\n**Below properties will be required for authentication of API calls.**\r\n    \r\n`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.\r\n`mastercard.consumer.key=`, this refers to your consumer key. Copy it from \"Keys\" section on your project page in [Mastercard Developers](https://developer.mastercard.com/dashboard)\r\n`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](https://developer.mastercard.com/dashboard).\r\n`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](https://developer.mastercard.com/dashboard).\r\n\r\n\r\n### Build and Execute \u003ca name=\"build-and-execute\"\u003e \u003c/a\u003e\r\n1. Run `mvn clean install` from the root of the project directory.\r\n    * When install is run, the [OpenAPI Generator plugin](#integrating-with-openapi-generator) will generate the sources for connecting to the Merchant Identifier API.\r\n2. run `java -jar target/merchantidentifier-api-reference-app-X.X.X.jar` to start the project.\r\n    - **Notice**: Replace `X` with version of the reference app.\r\n    - **Example**: `java -jar target/merchantidentifier-api-reference-app-1.0.0.jar`\r\n\r\n### Reference Application Usage \u003ca name=\"reference-application-usage\"\u003e\u003c/a\u003e\r\n- Use the merchant identifier reference app by providing merchant descriptor to get the matches.\r\n- click on a marker to open more information on the right panel.\r\n\r\n### Integrating with OpenAPI Generator \u003ca name=\"integrating-with-openapi-generator\"\u003e\u003c/a\u003e\r\n[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification). \r\nIt provides generators and library templates for supporting multiple languages and frameworks.\r\n\r\nSee also:\r\n* [OpenAPI Generator (maven Plugin)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin)\r\n* [OpenAPI Generator (executable)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-cli)\r\n* [CONFIG OPTIONS for java](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/java.md)\r\n\r\n#### OpenAPI Generator Plugin Configuration\r\n \r\n ```xml\r\n \u003cplugin\u003e\r\n     \u003cgroupId\u003eorg.openapitools\u003c/groupId\u003e\r\n     \u003cartifactId\u003eopenapi-generator-maven-plugin\u003c/artifactId\u003e\r\n     \u003cversion\u003e4.3.0\u003c/version\u003e\r\n     \u003cexecutions\u003e\r\n         \u003cexecution\u003e\r\n             \u003cgoals\u003e\r\n                 \u003cgoal\u003egenerate\u003c/goal\u003e\r\n             \u003c/goals\u003e\r\n             \u003cconfiguration\u003e\r\n                 \u003cinputSpec\u003e${project.basedir}/src/main/resources/merchant-identifier-api-spec.yaml\u003c/inputSpec\u003e\r\n                 \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\r\n                 \u003clibrary\u003eokhttp-gson\u003c/library\u003e\r\n                 \u003cconfigurationFile\u003e${project.basedir}/src/main/resources/openapi-config.json\u003c/configurationFile\u003e\r\n                 \u003cgenerateApiTests\u003efalse\u003c/generateApiTests\u003e\r\n                 \u003cgenerateModelTests\u003efalse\u003c/generateModelTests\u003e\r\n                 \u003cconfigOptions\u003e\r\n                     \u003csourceFolder\u003esrc/gen/java/main\u003c/sourceFolder\u003e\r\n                 \u003c/configOptions\u003e\r\n             \u003c/configuration\u003e\r\n         \u003c/execution\u003e\r\n     \u003c/executions\u003e\r\n \u003c/plugin\u003e\r\n ```\r\n\r\n## Use Cases \u003ca name=\"use-cases\"\u003e\u003c/a\u003e\r\n\r\n#### Parameters \u003ca name=\"parameters\"\u003e\u003c/a\u003e\r\nThese are the parameters used for the Merchant Identifier API.\r\n\r\n| Name                  | Type      | Default Value      | Purpose       |\r\n|-----------------------|-----------|--------------------|---------------|\r\n| merchant_descriptor   | string    | 0                  | To find merchant list with identifier.        |\r\n| match_type            | string    | ExactMatch         | To perform a type of the search for merchant identifiers |\r\n| card_acceptor_id      | string    | -                  | To find merchant list matched by card acceptor id |\r\n\r\n\r\n\u003e Get information on a Merchant Identifier. \r\n\r\n| MerchantIdentfier API URL         | Method        | Parameters                        | Request Model | Response model            |\r\n|-----------------------------------|---------------|-----------------------------------|---------------|---------------------------|\r\n| /merchants                        | GET           | merchant_descriptor, match_type   | string        | merchant list with address and merchant descriptor |\r\n| /merchants-by-card-acceptor-ids   | GET           | card_acceptor_id                  | string        | merchant list with address and card acceptor id |\r\n\r\n\r\n## API Reference \u003ca name=\"api-reference\"\u003e\u003c/a\u003e\r\n\r\n### Reference Application API Reference \u003ca name=\"ref-app-api-reference\"\u003e\u003c/a\u003e\r\n\r\n| Reference App URL                                         | Parameters                        | Reference App Usage                                               | Merchant Identifier Endpoint Used                     |\r\n|-----------------------------------------------------------|-----------------------------------|-------------------------------------------------------------------|-------------------------------------------------------|\r\n|**/merchant-identifier/merchants**                         | merchant_descriptor, match_type   | Search for merchant list with merchant identifier by match type   | /merchant-identifier/merchants                        |\r\n|**/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   |\r\n\r\nExample Search Requests in a rest client of your choice: \r\n* `https://sandbox.api.mastercard.com/merchant-identifier/merchants?merchant_descriptor=DOLIUMPTYLTDWELSHPOOLWA\u0026match_type=ExactMatch`\r\n* `https://sandbox.api.mastercard.com/merchant-identifier/merchants?merchant_descriptor=DOLIUMPTYLTDWELSHPOOLWA\u0026match_type=FuzzyMatch`\r\n* `https://sandbox.api.mastercard.com/merchant-identifier/merchants-by-card-acceptor-ids?card_acceptor_id=C928456`\r\n\r\n\r\n### Merchant Identifier API Reference \u003ca name=\"merchant-identifier-api-reference\"\u003e\u003c/a\u003e\r\n\r\nSee the [API Reference](https://developer.mastercard.com/merchant-identifier/documentation/api-reference) page in the documentation. \r\n\r\n| API Endpoint                  | Description                                                       |\r\n| ----------------------------- | ----------------------------------------------------------------- |\r\n| [Merchant Identifier](https://developer.mastercard.com/merchant-identifier/documentation/api-reference#api)                 | Search for merchant list with matching merchant identifier |\r\n\r\n## Authentication \u003ca name=\"authentication\"\u003e\u003c/a\u003e\r\n\r\n### Mastercard oauth1 Signer Library \u003ca name=\"oauth-library\"\u003e\u003c/a\u003e\r\nThis dependency is required to properly call the API.\r\n```xml\r\n\u003cdependency\u003e\r\n    \u003cgroupId\u003ecom.mastercard.developer\u003c/groupId\u003e\r\n    \u003cartifactId\u003eoauth1-signer\u003c/artifactId\u003e\r\n    \u003cversion\u003e1.2.3\u003c/version\u003e\r\n\u003c/dependency\u003e\r\n```\r\n[Link to the oauth1 library's Github](https://github.com/Mastercard/oauth1-signer-java)\r\n\r\n[Looking for other languages?](https://github.com/Mastercard?q=oauth\u0026type=\u0026language=)\r\n\r\nSee the code used in this application to utilize the library.\r\n```Java\r\nFound in /src/java/com.mastercard.midreferenceapplciation.config.ApiClientConfiguration\r\n\r\nApiClient client = new ApiClient();\r\nHttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor(logger::info);\r\nloggingInterceptor.level(HttpLoggingInterceptor.Level.BASIC);\r\ntry {\r\n    client.setBasePath(basePath);\r\n    client.setHttpClient(\r\n            client.getHttpClient()\r\n                    .newBuilder()\r\n                    .addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, getSigningKey()))\r\n                    .addInterceptor(loggingInterceptor)\r\n                    .build()\r\n    );\r\n\r\n    return client;\r\n} catch (Exception e) {\r\n    logger.error(\"Error occurred while configuring ApiClient\", e);\r\n}\r\nreturn client;\r\n```\r\n\r\n## Support \u003ca name=\"support\"\u003e\u003c/a\u003e\r\nIf you would like further information, please send an email to apisupport@mastercard.com\r\n\r\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\r\nLicensed 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\r\n \r\n       http://www.apache.org/licenses/LICENSE-2.0\r\n \r\nUnless 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.\r\n\r\n**Copyright © 1994-2022, All Rights Reserved by Mastercard.**\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fmerchant-identifier-reference-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Fmerchant-identifier-reference-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fmerchant-identifier-reference-app/lists"}