Personalized Offers Reference Implementation

Table of Contents

• Overview
• Usage
  • Frameworks / Libraries used
  • Requirements
• Integrating with OpenAPI Generator
  • OpenAPI Generator Plugin Configuration
• Configuration
• Use Cases
• Execute the Use-Cases
• Service Documentation
• API Reference
• Support
• License

Overview

Personalized Offers analyzes payment card transaction history to present cardholders with customized offers. This code showcases reference implementation of Personalized Offers APIs. Please see here for more details on the API: Mastercard Developer

Usage

Frameworks / Libraries used

• Spring Boot
• Okhttp
• Lombok
• Mockito
• OpenAPI Generator
• Apache Maven

Requirements

• Java 11 or above.
• Maven
• Lombok
  • Plugin for IntelliJ
  • Setup for Eclipse
  • Setup for Netbeans

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.

OpenAPI Generator Plugin Configuration

      <plugin>
        <groupId>org.openapitools</groupId>
        <artifactId>openapi-generator-maven-plugin</artifactId>
        <version>5.3.0</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
            <configuration>
              <inputSpec>${project.basedir}/src/main/resources/reference-service.yaml</inputSpec>
              <generatorName>java</generatorName>
              <apiPackage>com.mastercard.api</apiPackage>
              <modelPackage>com.mastercard.api.model</modelPackage>              
              <generateApiTests>false</generateApiTests>
              <generateModelTests>false</generateModelTests>
              <generateApiTests>false</generateApiTests>
              <generateModelDocumentation>false</generateModelDocumentation>
              <generateApiDocumentation>false</generateApiDocumentation>              
              <skipValidateSpec>true</skipValidateSpec>
              <configOptions>
                <sourceFolder>src/gen/java/main</sourceFolder>
                <supportingFiles>false</supportingFiles>
                <dateLibrary>java8</dateLibrary>              
              </configOptions>
            </configuration>
          </execution>
        </executions>
      </plugin>

For more information on how this client generator works please consult the official GitHub repository

Configuration

1. Open Mastercard Developers website and create an account at Mastercard Developer.
2. Create a new project here.
3. Add the Personalized Offers API to your project and click continue.
4. Configure project and click continue.
5. Download Sandbox Signing Key.
6. A .p12 file is downloaded automatically. Note: On Safari, the file name will be Unknown. Rename it to a .p12 extension.
7. Copy the downloaded .p12 file to src/main/resources folder in the code.
8. Open src/main/resources/application.properties and configure:
   • mastercard.api.p12.path - Path to keystore (.p12) file. Since the .p12 is under same resources folder just pass the name of the .p12 here.
   • mastercard.api.consumer.key - Consumer key. Copy this from "Sandbox/Production Keys" on your project page
   • mastercard.api.key.alias - Key alias. Default key alias for sandbox is keyalias.
   • mastercard.api.keystore.password - Keystore password. Default keystore password for sandbox project is keystorepassword.

Use Cases

Legacy User Presentment Use Cases

The following API use cases are the deprecated version of the current User Presentment APIs that are listed under User Presentment Use Cases

1. Retrieve Redeemed Offers
   As part of the consumer experience, Issuers or Partners can also provide a list of offers the cardholder has redeemed. This allows a cardholder to see their activity and understand which offers they may have used in the past, and the benefits they attained from the program.

2. Activate an Offer
   For attribution reasons, merchants want to know if a cardholder has seen an offer and plan to use it. An Issuer or Partner can activate an offer (based on a user action such as a click, or a page view) and enable that offer for use. Not all programs require an offer to be activated. This is determined during program implementation and Mastercard will consult with the Issuer/Partner on whether offers require an activation for use. Issuer or Partner can retrieve extended information about the specified activated Postpaid Credit offer.

3. User Feedback
   Issuer or Partner is allowed to provide a thumbs-up or a thumbs-down rating of the specified offer. Offer matches that are disliked will be suppressed from the results of future calls to Matched Offers. Issuer or Partner can retrieve feedback with offer ids based on the search criteria.

4. Retrieve Personalized Offers
   Issuer or Partner can get a list of offers that a cardholder was assigned based on their spend history. The offers are returned along with all the associated marketing content, terms and conditions, and logos/images. The Issuer or Partner can then take the offer content and integrate it into their app or site to create a seamless, integrated consumer experience for their cardholders.

5. Show the Total User Savings
   Similar to retrieving redeemed offers, an Issuer or Partner can also retrieve the total savings a cardholder has earned from the program and the total cash back or points they have accumulated from redeeming offers. Again, this is used to highlight the benefits a cardholder received from the program. Redeemed Offers is a line-by-line listing of all individual offers that were redeemed whereas User Savings only provide the aggregate sum of the cash back or points earned.

6. Retrieve User Token
   Issuer or Partner can create a user session token for a cardholder. It must be called prior to any other API calls for the specified cardholder. The token value does not expire.

7. Retrieve Offer Details
   Issuer or Partner can retrieve extended information for the requested offer, typically returns a detailed information of an offer.

More details on the Legacy User Presentment Use Cases can be found here.

Platform Admin Use Cases

1. Retrieve All Offers
   Issuer or Partner can get a list of all offers regardless of cardholder. Issuer or Partner can retrieve extended information for the requested offers.

2. Retrieve All Adjustments
   The Adjustments/Redemption API provides detailed information on the redemptions that has satisfied specific offer criteria in order to be eligible to receive cash back or points offered by merchant in collaboration with the issuer and Mastercard.

More details on the Platform Admin Use Cases can be found here.

User Presentment Use Cases

1. Retrieve Access Token
   The Access Tokens API responsible for generating access tokens. It must be called prior to any other user centered API calls.

2. Retrieve User Offers
   Retrieves a list of offers that were assigned to the cardholder based on his or her spend history. The offers are returned along with all the associated marketing content, terms and conditions, and logos/images.

3. Activate Offer
   Activates the given offer and makes it available for redemption to the cardholder.

4. Offer Rating
   Cardholder can submit a rating for an offer based on his or her preference (for example: like or dislike). Cardholder can also Retrieve the rating for the offer.

5. Retrieve Offer Ratings
   Cardholder can retrieve all ratings he or she submitted with the corresponding offer ids.

6. Retrieve Offer
   Cardholder can retrieve extended information for the requested offer, typically returns detailed information of an offer.

7. Retrieve User Adjustments
   Cardholder can retrieve all adjustments made that conform to the search criteria (if specified).

8. Retrieve User Savings
   Provides an overview of the accumulated and potential savings for a cardholder based on the redemptions made and the additional offers available for the cardholder.

9. Filter Personalized Offers Cardholder can filter the list of offers they were assigned based on a criteria provided. The offers are returned along with all the associated marketing content, terms and conditions, and logos/images.

More details on the User Presentment Use Cases can be found here.

Execute the Use-Cases

1. Run ./mvn clean install from the root of the project directory.
2. There are two ways to execute the use-cases:

   1. Execute the use-cases(test cases):

      • Go to src/test/java/com/mastercard/developer/usecases folder.
      • Execute each test cases.
      • In LegacyUserPresentmentServiceTest.java and PlatformAdminServiceTest.java, note that a Financial Institution Identifier (f-id) provided by Mastercard during implementation is required while executing all test cases.
      • In LegacyUserPresentmentServiceTest.java, note that a user-token is created using Financial Institution Identifier and AuthInfo (encrypted concatenation of "User ID as specified in enrollment:Financial Institute ID:current Unix time) provided by Mastercard during formal implementation project, the user-token is used while executing all the other test-cases.
      • In UserPresentmentServiceTest.java, note that an access-token is created using Financial Institution Identifier, user Id and UTC time offset. The access-token is used while executing all the other test-cases.
      • If you want to change any request parameters, please make change in Constant.javafrom src/main/java/com/mastercard/developer/constant folder.

   2. Use REST API based Client( such as Insomnia or Postman)

      • Run ./mvn spring-boot:run command to run the application.
      • Use any REST API based Client to test the functionality. Below are the endpoints exposed by this reference application, use locahost:8080 as the Host:
        • GET /redeem-offers
        • POST /activate-offers
        • GET /activation-details
        • POST /user-feedbacks
        • GET /user-feedbacks
        • GET /matched-offers
        • GET /user-savings
        • GET /user-tokens
        • GET /offer-details
        • GET /offers
        • GET /adjustments
        • POST /user-presentment/access-tokens
        • GET /user-presentment/offers
        • GET /user-presentment/offers/{offer_id}
        • POST /user-presentment/offers/filters
        • GET /user-presentment/offer-ratings
        • GET /user-presentment/offer-ratings/{offer_id}
        • POST /user-presentment/offer-ratings/{offer_id}/likes
        • POST /user-presentment/activations
        • GET /user-presentment/savings
        • GET /user-presentment/adjustments
        • GET /platform-admin/offers
        • POST /platform-admin/offers/filters
        • GET /platform-admin/adjustments
      • For more information about above endpoints, please refer PersonalizedOffersController.java from src/main/java/com/mastercard/developer/controller folder.

Service Documentation

Personalized Offers service documentation can be found here

API Reference

The API Reference can be found here

Support

Please email [email protected] with any questions or feedback you may have.

License

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