- Overview
- Usage
- Integrating with OpenAPI Generator
- Configuration
- Use Cases
- Execute the Use-Cases
- Service Documentation
- API Reference
- Support
- License
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
OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.
<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
- Open Mastercard Developers website and create an account at Mastercard Developer.
- Create a new project here.
- Add the
Personalized Offers
API to your project and click continue. - Configure project and click continue.
- Download Sandbox Signing Key.
- A
.p12
file is downloaded automatically. Note: On Safari, the file name will beUnknown
. Rename it to a .p12 extension. - Copy the downloaded
.p12
file tosrc/main/resources
folder in the code. - 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 pagemastercard.api.key.alias
- Key alias. Default key alias for sandbox iskeyalias
.mastercard.api.keystore.password
- Keystore password. Default keystore password for sandbox project iskeystorepassword
.
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
-
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. -
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. -
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. -
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. -
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. -
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. -
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
-
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. -
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.
-
Retrieve Access Token
The Access Tokens API responsible for generating access tokens. It must be called prior to any other user centered API calls. -
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. -
Activate Offer
Activates the given offer and makes it available for redemption to the cardholder. -
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. -
Retrieve Offer Ratings
Cardholder can retrieve all ratings he or she submitted with the corresponding offer ids. -
Retrieve Offer
Cardholder can retrieve extended information for the requested offer, typically returns detailed information of an offer. -
Retrieve User Adjustments
Cardholder can retrieve all adjustments made that conform to the search criteria (if specified). -
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. -
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.
- Run
./mvn clean install
from the root of the project directory. - There are two ways to execute the use-cases:
-
Execute the use-cases(test cases):
- Go to
src/test/java/com/mastercard/developer/usecases
folder. - Execute each test cases.
- In
LegacyUserPresentmentServiceTest.java
andPlatformAdminServiceTest.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.java
fromsrc/main/java/com/mastercard/developer/constant
folder.
- Go to
-
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
fromsrc/main/java/com/mastercard/developer/controller
folder.
- Run
-
Personalized Offers service documentation can be found here
The API Reference can be found here
Please email [email protected] with any questions or feedback you may have.
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:
https://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.