SBDE API Reference Application

Table of Contents

• Overview
  • Compatibility
  • References
  • Tutorial
  • Frameworks
• Setup
  • Prerequisites
  • Application Configuration
  • Build and Execute
  • Reference Application Usage
  • Integrating with OpenAPI Generator
• Use Cases
  • Merchant Location
  • Merchant Daily Metrics
  • Merchant Performance Metrics
• API Reference
• Authentication
  • Mastercard's OAuth Library
• Glossary
• Support
• License

Overview

This project showcases the use case of retrieving sbde metrics using the SBDE API v2. This application illustrates connecting to the SBDE API using Mastercard's OAuth library. You will need a consumer key, .p12 files, and your keystore alias and password. This application is the output of a tutorial from sbde V2.

Compatibility

• Java 8 or later

References

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

Tutorial

A tutorial can be found here for setting up and using this service.

Frameworks

• Spring
• OpenAPI Generator
• Java 8+
• Maven

Setup

Prerequisites

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

Application Configuration

1. Create an account at Mastercard Developers.
2. Create a new project and add the SBDE API to your project.
   • A zip file will be downloaded automatically with your keys.
3. Take note of the given consumer key, keyalias, and keystore password given upon the project creation.
4. Copy the downloaded .p12 file to /src/main/resources.
5. Update the properties found in src/main/java/com/mastercard/sbde/ApiService.java.

    private static final String API_BASE_PATH = "https://sandbox.api.mastercard.com/sbde/metrics-api";
    
    //Below properties will be required for authentication of API calls.
    private static final String CONSUMER_KEY = "Your 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)
    private static final String SIGNING_KEY_ALIAS = "your key alias"; // 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).
    private static final String SIGNING_KEY_FILE_PATH = "path to your.p12 private key file"; // This refers to .p12 file found in the signing key. Please place .p12 file at src\main\resources in the project folder and add classpath for .p12 file.
    private static final String SIGNING_KEY_PASSWORD = "your password"; // 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).

Build and Execute

6. Run mvn clean compile from the root of the project directory.
   • When compile is run, the OpenAPI Generator plugin will generate the sources for connecting to the SBDE API.
7. run mvn exec:java -Dexec.mainClass="com.mastercard.sbde.Main" to run the project.

Reference Application Usage

• Select an endpoint from the dropdown menu at the top of the application
• Fill in the required parameters and click submit
• Click on 'JSON Response' to view the raw JSON returned by the API call

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>3.3.4</version>
   <executions>
       <execution>
           <id> Small Business Decision Enhancer 2.0 REST Client</id>
           <goals>
               <goal>generate</goal>
           </goals>
           <configuration>
               <inputSpec>${project.basedir}/src/main/resources/small-business-decision-enhancer.yaml</inputSpec>
               <generateApiTests>false</generateApiTests>
               <generateModelTests>false</generateModelTests>
               <generatorName>java</generatorName>
               <configOptions>
                   <sourceFolder>src/gen/java/main</sourceFolder>
                   <dateLibrary>java8</dateLibrary>
               </configOptions>
           </configuration>
       </execution>
   </executions>
</plugin>

Use Cases

These are the parameters used for the SBDE API. All parameters are optional.

Name	Type	Default Value	Purpose
from_date	string	null	Date in formation yyyy-MM-dd. Used as the most recent date to search for.
to_date	string	null	Date in formation yyyy-MM-dd. Used as the oldest date to search for.
offset	int	0	For Pagination; offset is used to offset the start of the list.
limit	int	25	For Pagination; limit is used to limit the number of entities returned
sort	string	+period	Sorts the results + for ascending, - for descending and any property from the result.

Merchant Location

Get information on a specific merchant location.

URL	Method	Parameters	Request Model	Response model
/merchant-locations/{merchant_location_id}	GET	-	int	MerchantLocation

Merchant Daily Metrics

Get a paginated list of all merchant location daily metrics.

URL	Method	Parameters	Request Model	Response model
/merchant-locations/{merchant_location_id}/metrics/daily-metrics	GET	from_date, to_date, offset, limit, sort	int	MerchantLocationDailyMetrics

Merchant Performance Metrics

Get a list of all merchant location performance metrics.

URL	Method	Parameters	Request Model	Response model
/merchant-locations/{merchant_location_id}/metrics/merchant-performance-metrics	GET	from_date, to_date, sort	int	MerchantLocationPerformanceMetrics

API Reference

See the API Reference page in the documentation.

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.sbde.ApiService

ApiClient client = new ApiClient();
        client.setBasePath(API_BASE_PATH); //If you use any other sandbox url then please add sbde/metrics-api as an extension
        client.setDebugging(true);

        List<Interceptor> interceptors = client.getHttpClient().networkInterceptors();
        interceptors.add(new Main.ForceJsonResponseInterceptor());
        interceptors.add(new OkHttp2OAuth1Interceptor(CONSUMER_KEY, signingKey));

        merchantLocationApi = new MerchantLocationApi(client);
        merchantLocationMetricsApi = new MerchantLocationMetricsApi(client);
        merchantLocationPerformanceMetricsApi = new MerchantLocationPerformanceMetricsApi(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-2020, All Rights Reserved by Mastercard.