{"id":28577623,"url":"https://github.com/mastercard/locations-merchants-api-reference-app","last_synced_at":"2025-06-11T00:39:01.815Z","repository":{"id":186133641,"uuid":"674695093","full_name":"Mastercard/locations-merchants-api-reference-app","owner":"Mastercard","description":null,"archived":false,"fork":false,"pushed_at":"2023-08-04T14:46:10.000Z","size":37,"stargazers_count":0,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-16T10:43:17.203Z","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","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-04T14:42:09.000Z","updated_at":"2023-08-04T14:45:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"e9b5aadb-73f1-44b8-8d92-3ff908611b82","html_url":"https://github.com/Mastercard/locations-merchants-api-reference-app","commit_stats":null,"previous_names":["mastercard/locations-merchants-api-reference-app"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flocations-merchants-api-reference-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flocations-merchants-api-reference-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flocations-merchants-api-reference-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flocations-merchants-api-reference-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/locations-merchants-api-reference-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Flocations-merchants-api-reference-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177341,"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:35.701Z","updated_at":"2025-06-11T00:39:01.755Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Locations Merchants 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    * [Request Body](#bodyparams)\r\n    * [Countries](#countries)\r\n    * [Country SubDivisions](#country-subdivisions)\r\n    * [Merchant Categories](#categories)\r\n    * [Merchant Searches](#searches)\r\n- [API Reference](#api-reference)\r\n    - [Reference App API Reference](#ref-app-api-reference)\r\n    - [Locations Merchants API Reference](#locations-merchants-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 locations using the [Locations Merchants API](https://developer.mastercard.com/locations/documentation/).\r\n\r\nThis application illustrates connecting to the Locations Merchants 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/jdk11-archive-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- [Spring](https://spring.io/projects/spring-boot)\r\n- [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator)\r\n- [Java 11](https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html)\r\n- [Maven](https://maven.apache.org/download.cgi)\r\n\r\n## Setup \u003ca name=\"setup\"\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/javase/jdk11-archive-downloads.html)\r\n* [Spring Boot 2.2+](https://spring.io/projects/spring-boot)\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 `Locations` 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 the zip file which contains `.p12` file.\r\n4. Update your credentials in 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/locations/merchants`, is the sandbox application URL to connect to Mastercard. \r\n - **Note**: For production usage, use `https://api.mastercard.com/locations/merchants`.\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 the downloaded .p12 file path 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 alias. If it is modified, use the updated one from keys section in [Mastercard Developers](https://developer.mastercard.com/dashboard). \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 Locations API.\r\n2. run `java -jar target/locations-merchants-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/locations-merchants-reference-app-1.0.0.jar`\r\n3. Navigate to `http://localhost:8080/` in your browser.\r\n    - **Example**: `http://localhost:8080//locations/merchants/countries` a GET call to retrieve countries endpoint for Merchant Locations country list.\r\n    - **Example**: `http://localhost:8080/locations/merchants/country-subdivisions?country_code=USA` a GET call to retrieve USA country sub divisions endpoint for Merchant Locations country sub division list.\r\n    \r\n### Requesting a Merchant Searches POST call\u003ca name=\"searches-post-call\"\u003e \u003c/a\u003e\r\n1. A tool like Postman or Insomnia is needed to perform a POST call\r\n\r\n2. select the option POST from the HTTP request dropdown.\r\n\r\n3. Provide the URL in the address bar. \r\n    - **Example**: `http://localhost:8080/locations/merchants/searches`\r\n\r\n4. Select the BODY tab around the address bar and select the option type JSON.\r\n\r\n5. A Merchant location search can be performed either by longitude, latitude or by address and postal code like in the below example in BODY.\r\n    - Example: \r\n    ```\r\n                    {\r\n                        \"longitude\":\"38.6270\",\r\n                        \"latitude\":\"-90.1994\",\r\n                        \"merchantType\":\"paypass\"\r\n                    }\r\n    ```\r\n    - Example: \r\n    ```\r\n                    {\r\n                       \"addressLine1\":\"1 CONVENTION CENTER PLZ\",\r\n                       \"addressLine2\":\"\",\r\n                       \"city\":\"SAINT CHARLES\",\r\n                       \"countryCode\":\"USA\",\r\n                       \"countrySubdivisionCode\":\"MO\",\r\n                       \"postalCode\":\"63303\",\r\n                       \"merchantType\":\"paypass\"\r\n                    }\r\n    ```\r\n\r\n### Reference Application Usage \u003ca name=\"reference-application-usage\"\u003e\u003c/a\u003e\r\n- Use the locations app in the sandbox to find merchant searches.\r\n- click on a marker to open more information on the right panel.\r\n- click on right panel to expand the marker to make calls.\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/locations-merchants-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 Locations API. Few parameters are required.\r\n\r\n| Name                      | Type      | Default Value      | Purpose       |\r\n|---------------------------|-----------|--------------------|---------------|\r\n| client_id                 | String    | null               | For countries; client_id is used to identify the client performing the search.        |\r\n| country_code              | String    |                    | For country subdivisions; country_code is used to identify the country to be searched. |\r\n| offset                    | int       | 0                  | For Pagination; offset is used to offset the start of the list.        |\r\n| limit                     | int       | 25                 | For Pagination; limit is used to limit the number of entities returned |\r\n| distance                  | int       | 5                  | For Merchants location information search based on radius; distance is used to search the length of distance from the centroid point. |\r\n| distanceUnit              | String    | MILE               | Unit of measurement for calculating the radius search; Measurement of distance unit in miles or kilometers. Value string (MILE or KM) |\r\n\r\n#### RequestBody \u003ca name=\"bodyparams\"\u003e\u003c/a\u003e\r\nThese are the parameters used for the Locations API. Few parameters are required.\r\n\r\n| Name                      | Type      | Default Value | Purpose       |\r\n|---------------------------|-----------|---------------|---------------|\r\n| addressLine1              | String    |               | For Merchants search; AddressLine1 is used to search the Merchants locations based on the address|\r\n| addressLine2\t            | String    |               | For Merchants search; AddressLine2 is used to search the Merchants locations based on the address |\r\n| city                      | String    |               | For Merchants search; City is used to search the Merchants locations based of address|\r\n| countrySubdivisionCode    | String    |               | For Merchants search; City is used to search the Merchants locations based of address |\r\n| latitude                  | String    |               | For Merchants search ; latitude is used to perform Merchants search based on latitude and longitude|\r\n| longitude                 | String    |               | For Merchants search ; latitude is used to perform Merchants search based on latitude and longitude |\r\n| postalCode                | String    |               | For Merchants search; postal code is used to search Merchants locations based on the address|\r\n| merchantType              | String    |               | For merchants location information offering services around 5 mile radius by specific coordinates or using a address; Type of merchant location. Options are 'paypass' 'repower' 'easysavings' and 'cashback'. |\r\n\r\n\r\n\r\n### Countries \u003ca name=\"countries\"\u003e\u003c/a\u003e\r\n\u003e Get All Countries information. \r\n\r\n| Locations Merchants API URL    | Method        | Parameters        | Request Model | Response model|\r\n|--------------------------------|---------------|-------------------|---------------|---------------|\r\n| /countries                     | GET           | client_id         |               | Countries     | \r\n\r\n### Country SubDivisions \u003ca name=\"country-subdivisions\"\u003e\u003c/a\u003e\r\n\u003e Get Country Subdivisions based on country code. \r\n\r\n| Locations Merchants API URL    | Method        | Parameters            | Request Model | Response model        |\r\n|--------------------------------|---------------|-----------------------|---------------|-----------------------|\r\n| /country-subdivisions          | GET           |countryCode, client_id |               | CountrySubdivisions   |\r\n\r\n### Merchant Categories \u003ca name=\"categories\"\u003e\u003c/a\u003e\r\n\u003e Get All merchant categories supported. \r\n\r\n| Locations Merchants API URL    | Method        | Parameters        | Request Model | Response model|\r\n|--------------------------------|---------------|-------------------|---------------|---------------|\r\n| /categories                    | GET           | client_id         |               | Categories    | \r\n\r\n\r\n### Merchant Searches \u003ca name=\"searches\"\u003e\u003c/a\u003e\r\n\u003e Retrieving Merchants locations based on a latitude/longitude or on a physical address or postal code \r\n\r\n| Locations Merchants API URL    | Method        | Parameters                        | BodyParameters                                                                                     | Request Model   | Response model|\r\n|--------------------------------|---------------|-----------------------------------|----------------------------------------------------------------------------------------------------|-----------------|---------------|\r\n| /searches                      | POST          | offset,limit,distance,distanceUnit| addressLine1,addressLine2,city,countrySubdivisionCode,latitude,longitude,postalcode,merchantType   | MerchantSearch  | Merchants     |\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             | Locations Merchants Endpoint Used  |\r\n|------------------------------------------------|--------------------------------------------------|---------------------------------|-----------------------|\r\n|**/locations/merchants/countries**              | client_id                                        | Lists countries that have Merchants offering services | /locations/merchants/countries |\r\n|**/locations/merchants/country-subdivisions**   | country_code,client_id                           | Lists country subdivisions that have Merchants offering the following services by country code USA or CAN | /locations/merchants/country-subdivisions |\r\n|**/locations/merchants/categories**             | client_id                                        | Lists all the merchant categories supported | /locations/merchants/categories |\r\n|**/locations/merchants/searches**               | offset,limit,distance,distanceUnit,merchantType  | Lists merchants location information offering services around 5 mile radius by specific coordinates or using a address | /locations/merchants/searches |\r\nExample Search Request in a rest client (or browser) of your choice: `http://localhost:8080/locations/merchants/searches?latitude=45.50977\u0026longitude=-73.55163`\r\n\r\n### Locations Merchants API Reference \u003ca name=\"locations-merchants-api-reference\"\u003e\u003c/a\u003e\r\n\r\nSee the [API Reference](https://developer.mastercard.com/locations/documentation/api-reference/) page in the documentation. \r\n\r\n| API Endpoint                                                                                                   | Description                                                       |\r\n| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |\r\n| [Get Countries](https://developer.mastercard.com/locations/documentation/api-reference#api)                    | Lists countries that have Merchants offering services    |\r\n| [Get Country Subdivisions Details](https://developer.mastercard.com/locations/documentation/api-reference#api) | Lists country subdivisions that have Merchants offering the following services by country code USA or CAN    |\r\n| [Get Merchants category](https://developer.mastercard.com/locations/documentation/api-reference#api)           | Lists all the merchant categories supported  |\r\n| [Post Merchants Search](https://developer.mastercard.com/locations/documentation/api-reference#api)            | Lists merchants location information offering services by specific coordinates or using a address    |\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.locationsatmsreferenceapplication.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-2023, All Rights Reserved by Mastercard.**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Flocations-merchants-api-reference-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Flocations-merchants-api-reference-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Flocations-merchants-api-reference-app/lists"}