Mastercard Rebates Reference Implementation

Table of Contents

• Overview
  • Compatibility
  • References
• Usage
  • Prerequisites
  • Configuration
  • Integrating with OpenAPI Generator
  • Build and Execute
• Use Cases
• API Reference
  • Authorization
  • Request Examples
  • Recommendation
• Support
• License

Overview

Mastercard Rebates services is a standalone API that provides clients with the capability of initiating statement credit to a Mastercard card account, independent of the promotion rule and reward scoring. This API can be used by the client to handle exception cases with rebate processing or reward scoring. Please see here for more details on the API: Mastercard Developers.

Compatibility

• Java 8 or later

References

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

Usage

Prerequisites

• Mastercard Developers Account with access to Mastercard Rebates API
• A text editor or IDE
• Spring Boot 2.2+
• Apache Maven 3.3+
• Set up the JAVA_HOME environment variable to match the location of your Java installation.

Configuration

• Create an account at Mastercard Developers.

• Create a new project and add Mastercard Rebates API to your project.

• Configure project and download signing key. It will download the zip file.

• Select .p12 file from zip and copy it to src/main/resources in the project folder.

• Open ${project.basedir}/src/main/resources/application.properties and configure below parameters.

  mastercard.api.base.path=https://sandbox.api.mastercard.com/loyalty/rewards/rebates, its a static field, will be used as a host to make API calls.

  Below properties will be required for authentication of API calls.

  mastercard.api.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.

  mastercard.api.consumer.key=, this refers to your consumer key. Copy it from "Keys" section on your project page in Mastercard Developers

  mastercard.api.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.api.keystore.password=keystorepassword, this is the default value of key alias. If it is modified, use the updated one from keys section in Mastercard Developers.

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

<!-- https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin -->
<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi-generator.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/Mastercard_Rebates-api-spec.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/main/java</sourceFolder>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Generating The API Client Sources

Now that you have all the dependencies you need, you can generate the sources. To do this, use one of the following two methods:

Using IDE

• Method 1
  In IntelliJ IDEA, open the Maven window (View > Tool Windows > Maven). Click the icons Reimport All Maven Projects and Generate Sources and Update Folders for All Projects

• Method 2
  

  In the same menu, navigate to the commands ({Project name} > Lifecycle), select clean and compile then click the icon Run Maven Build.

Using Terminal

• Navigate to the root directory of the project within a terminal window and execute mvn clean compile command.

Build and Execute

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/mastercard-rebates-reference-1.0.0.jar

Use Cases

Case 1: REBATE WITH ACCOUNT IDENTIFIER

• This endpoint provides the capability to non PCI certified loyalty providers to offer rebates for all the rewards enrolled accounts mapped to Mastercard generated or client provided account identifiers.

• Here, the transactions performed by cardholder is scored by Loyalty providers for reward program enrolled accounts and as being the non PCI certified providers would send the transactions using account identifiers to Mastercard to award rebates.

• Refer to model classes for field level information.

  URL	Method	Request	Response
  /rebate-transactions	POST	RebateTransactions	RebateTransactionResponse

Case 2: REBATE WITH DPAN

• This endpoint provides the capability to loyalty providers to offer rebates for all the Mastercard accounts mapped to DPAN token irrespective of the accounts enrollment into rewards program.

• Here, the DPAN transactions performed by cardholder is scored by Loyalty providers and rebate processed by Mastercard.

• Refer to model classes for field level information.

  URL	Method	Request	Response
  /rebate-transactions	POST	RebateTransactions	RebateTransactionResponse

Case 3: REBATE WITH PAN

• This endpoint provides the capability to loyalty providers to offer rebates for all the Mastercard accounts with PAN irrespective of the accounts enrollment into rewards program.

• Here, the PAN transactions performed by cardholder is scored by Loyalty providers and rebate processed by Mastercard.

• Refer to model classes for field level information.

  URL	Method	Request	Response
  /rebate-transactions	POST	RebateTransactions	RebateTransactionResponse

Case 4: ERROR HANDLING

• The operation can fail for various reasons like formatting, field length exceeds, etc.
• This use case just shows one of the example of such failures.
• For the complete list of application specific error codes, refer to Application Error Codes.
• Also refer to model class Errors for field level information.

API Reference

To develop a client application that consumes a RESTful Rebates API with Spring Boot, refer below documentation.

API	Endpoint	HTTP Method	Description
Create Rebate Transaction	/rebate-transactions	POST	This send rebate requests for processing the accounts which may or may not be enrolled into rewards program.

Authorization

The com.mastercard.developer.interceptors package will provide you with some request interceptor classes you can use when configuring your API client. These classes will take care of adding the correct Authorization header before sending the request.

Request Examples

You can change the default input passed to APIs, modify values in following files,

• com.mastercard.developer.example.RebateTransactionExample.java

Recommendation

It is recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Support

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

License

Copyright 2020 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.