{"id":28577530,"url":"https://github.com/mastercard/personalized-offers-reference-app","last_synced_at":"2025-07-04T19:07:30.650Z","repository":{"id":39930707,"uuid":"290288599","full_name":"Mastercard/personalized-offers-reference-app","owner":"Mastercard","description":"Personalized Offers Reference Implementation","archived":false,"fork":false,"pushed_at":"2024-10-30T17:51:59.000Z","size":265,"stargazers_count":2,"open_issues_count":2,"forks_count":8,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-30T18:37:40.619Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.mastercard.com","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":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-25T18:09:37.000Z","updated_at":"2024-10-30T17:48:26.000Z","dependencies_parsed_at":"2024-03-14T19:46:30.244Z","dependency_job_id":"8515143f-0afb-427f-8493-641cf696eb08","html_url":"https://github.com/Mastercard/personalized-offers-reference-app","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpersonalized-offers-reference-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpersonalized-offers-reference-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpersonalized-offers-reference-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpersonalized-offers-reference-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/personalized-offers-reference-app/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpersonalized-offers-reference-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177333,"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:07.703Z","updated_at":"2025-06-11T00:38:53.596Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Personalized Offers Reference Implementation\n[![](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)\n\n## Table of Contents\n- [Overview](#overview)\n- [Usage](#usage)\n  * [Frameworks / Libraries used](#prerequisites)\n  * [Requirements](#requirements)\n- [Integrating with OpenAPI Generator](#integrating-with-openapi-generator)\n  * [OpenAPI Generator Plugin Configuration](#openapi-generator-plugin-configuration)\n- [Configuration](#configuration)  \n- [Use Cases](#use-cases)\n- [Execute the Use-Cases](#execute-the-use-cases)\n- [Service Documentation](#service-documentation)\n- [API Reference](#api-reference)\n- [Support](#support)\n- [License](#license)\n\n## Overview \u003ca name=\"overview\"\u003e\u003c/a\u003e\n\nPersonalized Offers analyzes payment card transaction history to present cardholders with customized offers.\nThis code showcases reference implementation of Personalized Offers APIs. Please see here for more details on the API: \n[Mastercard Developer](https://developer.mastercard.com/product/personalized-offers)\n\n## Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\n### Frameworks / Libraries used \u003ca name=\"prerequisites\"\u003e\u003c/a\u003e\n\n- [Spring Boot](https://spring.io/projects/spring-boot)\n- [Okhttp](https://square.github.io/okhttp/)\n- [Lombok](https://projectlombok.org/)\n- [Mockito](https://site.mockito.org/)\n- [OpenAPI Generator](https://openapi.tools/)\n- [Apache Maven](https://maven.apache.org/)\n\n### Requirements \u003ca name=\"requirements\"\u003e\u003c/a\u003e\n- [Java 11](https://www.oracle.com/java/technologies/downloads/) or above.\n- [Maven](https://maven.apache.org/download.cgi)\n- [Lombok](https://projectlombok.org/)\n  - [Plugin for IntelliJ](https://plugins.jetbrains.com/plugin/6317-lombok/)\n  - [Setup for Eclipse](https://projectlombok.org/setup/eclipse)\n  - [Setup for Netbeans](https://projectlombok.org/setup/netbeans)\n \n \n## Integrating with OpenAPI Generator \u003ca name=\"integrating-with-openapi-generator\"\u003e\u003c/a\u003e\n[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from \n[OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification). \nIt provides generators and library templates for supporting multiple languages and frameworks.\n\n### OpenAPI Generator Plugin Configuration \u003ca name=\"openapi-generator-plugin-configuration\"\u003e\u003c/a\u003e\n\n```xml\n      \u003cplugin\u003e\n        \u003cgroupId\u003eorg.openapitools\u003c/groupId\u003e\n        \u003cartifactId\u003eopenapi-generator-maven-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e5.3.0\u003c/version\u003e\n        \u003cexecutions\u003e\n          \u003cexecution\u003e\n            \u003cgoals\u003e\n              \u003cgoal\u003egenerate\u003c/goal\u003e\n            \u003c/goals\u003e\n            \u003cconfiguration\u003e\n              \u003cinputSpec\u003e${project.basedir}/src/main/resources/reference-service.yaml\u003c/inputSpec\u003e\n              \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n              \u003capiPackage\u003ecom.mastercard.api\u003c/apiPackage\u003e\n              \u003cmodelPackage\u003ecom.mastercard.api.model\u003c/modelPackage\u003e              \n              \u003cgenerateApiTests\u003efalse\u003c/generateApiTests\u003e\n              \u003cgenerateModelTests\u003efalse\u003c/generateModelTests\u003e\n              \u003cgenerateApiTests\u003efalse\u003c/generateApiTests\u003e\n              \u003cgenerateModelDocumentation\u003efalse\u003c/generateModelDocumentation\u003e\n              \u003cgenerateApiDocumentation\u003efalse\u003c/generateApiDocumentation\u003e              \n              \u003cskipValidateSpec\u003etrue\u003c/skipValidateSpec\u003e\n              \u003cconfigOptions\u003e\n                \u003csourceFolder\u003esrc/gen/java/main\u003c/sourceFolder\u003e\n                \u003csupportingFiles\u003efalse\u003c/supportingFiles\u003e\n                \u003cdateLibrary\u003ejava8\u003c/dateLibrary\u003e              \n              \u003c/configOptions\u003e\n            \u003c/configuration\u003e\n          \u003c/execution\u003e\n        \u003c/executions\u003e\n      \u003c/plugin\u003e\n```\nFor more information on how this client generator works please consult the official \n[GitHub repository](https://github.com/OpenAPITools/openapi-generator)\n\n## Configuration \u003ca name=\"configuration\"\u003e\u003c/a\u003e\n\n1.  Open Mastercard Developers website and create an account at [Mastercard Developer](https://developer.mastercard.com).\n2.  Create a new project [here](https://developer.mastercard.com/dashboard).\n3.  Add the `Personalized Offers` API to your project and click continue.\n4.  Configure project and click continue.\n5.  Download Sandbox Signing Key.\n6.  A `.p12` file is downloaded automatically. **Note**: On Safari, the file name will be `Unknown`. Rename it to a \n    .p12 extension.\n7.  Copy the downloaded `.p12` file to `src/main/resources` folder in the code.\n8.  Open `src/main/resources/application.properties` and configure:\n      - `mastercard.api.p12.path` - Path to keystore (.p12) file. Since the .p12 is under same resources folder just \n      pass the name of the .p12 here.\n      - `mastercard.api.consumer.key` - Consumer key. Copy this from \"Sandbox/Production Keys\" on your project page\n      - `mastercard.api.key.alias` - Key alias. Default key alias for sandbox is `keyalias`.\n      - `mastercard.api.keystore.password` - Keystore password. Default keystore password for sandbox project is \n      `keystorepassword`.\n\n## Use Cases \u003ca name=\"use-cases\"\u003e\u003c/a\u003e\n\n**Legacy User Presentment Use Cases**\n\nThe following API use cases are the deprecated version of the current User Presentment APIs that are listed under [User Presentment Use Cases](#user-presentment-use-cases)\n\n1. **Retrieve Redeemed Offers**  \nAs part of the consumer experience, Issuers or Partners can also provide a list of offers the cardholder has \nredeemed. This allows a cardholder to see their activity and understand which offers they may have used in the past, \nand the benefits they attained from the program.\n\n2. **Activate an Offer**  \n For attribution reasons, merchants want to know if a cardholder has seen an offer and plan to use it. An Issuer or \nPartner can activate an offer (based on a user action such as a click, or a page view) and enable that offer for use.\nNot all programs require an offer to be activated. This is determined during program implementation and Mastercard \nwill consult with the Issuer/Partner on whether offers require an activation for use.\nIssuer or Partner can retrieve extended information about the specified activated Postpaid Credit offer.\n\n3. **User Feedback**  \nIssuer or Partner is allowed to provide a thumbs-up or a thumbs-down rating of the specified offer. Offer matches \nthat are disliked will be suppressed from the results of future calls to Matched Offers. Issuer or Partner can \nretrieve feedback with offer ids based on the search criteria.\n\n4. **Retrieve Personalized Offers**  \nIssuer or Partner can get a list of offers that a cardholder was assigned based on their spend history. The offers \nare returned along with all the associated marketing content, terms and conditions, and logos/images. The Issuer or \nPartner can then take the offer content and integrate it into their app or site to create a seamless, integrated \nconsumer experience for their cardholders.\n  \n5. **Show the Total User Savings**  \nSimilar to retrieving redeemed offers, an Issuer or Partner can also retrieve the total savings a cardholder has \nearned from the program and the total cash back or points they have accumulated from redeeming offers. Again, this \nis used to highlight the benefits a cardholder received from the program. Redeemed Offers is a line-by-line listing \nof all individual offers that were redeemed whereas User Savings only provide the aggregate sum of the cash back or \npoints earned.\n  \n6. **Retrieve User Token**  \nIssuer or Partner can create a user session token for a cardholder. It must be called prior to any other API calls \nfor the specified cardholder. The token value does not expire.\n  \n7. **Retrieve Offer Details**  \nIssuer or Partner can retrieve extended information for the requested offer, typically returns a detailed \ninformation of an offer.\n  \nMore details on the Legacy User Presentment Use Cases can be found [here](https://developer.mastercard.com/pclo-presentment/documentation/legacy-user-presentment/use-cases/).  \n  \n**Platform Admin Use Cases**  \n\n1. **Retrieve All Offers**  \nIssuer or Partner can get a list of all offers regardless of cardholder. Issuer or Partner can retrieve \nextended information for the requested offers.\n  \n2. **Retrieve All Adjustments**  \nThe Adjustments/Redemption API provides detailed information on the redemptions that has satisfied specific offer \ncriteria in order to be eligible to receive cash back or points offered by merchant in collaboration with the issuer\nand Mastercard.\n   \nMore details on the Platform Admin Use Cases can be found [here](https://developer.mastercard.com/pclo-presentment/documentation/use-cases/platform-admin/).    \n   \n##### User Presentment Use Cases \u003ca name=\"user-presentment-use-cases\"\u003e\u003c/a\u003e\n   \n1. **Retrieve Access Token**  \nThe Access Tokens API responsible for generating access tokens. It must be called prior to any other user centered \nAPI calls.\n  \n2. **Retrieve User Offers**  \nRetrieves a list of offers that were assigned to the cardholder based on his or her spend history. \nThe offers are returned along with all the associated marketing content, terms and conditions, and logos/images.\n\n3. **Activate Offer**  \nActivates the given offer and makes it available for redemption to the cardholder.\n  \n4. **Offer Rating**  \nCardholder can submit a rating for an offer based on his or her preference (for example: like or dislike).\nCardholder can also Retrieve the rating for the offer.\n  \n5. **Retrieve Offer Ratings**  \nCardholder can retrieve all ratings he or she submitted with the corresponding offer ids.\n\n6. **Retrieve Offer**  \nCardholder can retrieve extended information for the requested offer, typically returns detailed information of an offer.\n\n7. **Retrieve User Adjustments**  \nCardholder can retrieve all adjustments made that conform to the search criteria (if specified).\n\n8. **Retrieve User Savings**  \nProvides an overview of the accumulated and potential savings for a cardholder based on the redemptions made and the additional offers available for the cardholder.                \n\n9. **Filter Personalized Offers**\nCardholder 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.\n  \nMore details on the User Presentment Use Cases can be found [here](https://developer.mastercard.com/pclo-presentment/documentation/use-cases/user-presentment/).      \n\n## Execute the Use-Cases   \u003ca name=\"execute-the-use-cases\"\u003e\u003c/a\u003e\n1. Run `./mvn clean install` from the root of the project directory.\n2. There are two ways to execute the use-cases:\n    1. Execute the use-cases(test cases):  \n        - Go to `src/test/java/com/mastercard/developer/usecases` folder.  \n        - Execute each test cases.\n        - 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.\n        - 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.\n        - 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.\n        - If you want to change any request parameters, please make change in `Constant.java`from `src/main/java/com/mastercard/developer/constant` folder.\n    \n    2. Use REST API based Client( such as [Insomnia](https://insomnia.rest/download) or [Postman](https://www.postman.com/downloads/))  \n        - Run `./mvn spring-boot:run` command to run the application.  \n        - 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:  \n          - GET \u003cHost\u003e/redeem-offers      \n          - POST \u003cHost\u003e/activate-offers  \n          - GET \u003cHost\u003e/activation-details  \n          - POST \u003cHost\u003e/user-feedbacks      \n          - GET \u003cHost\u003e/user-feedbacks  \n          - GET \u003cHost\u003e/matched-offers  \n          - GET \u003cHost\u003e/user-savings             \n          - GET \u003cHost\u003e/user-tokens  \n          - GET \u003cHost\u003e/offer-details  \n          - GET \u003cHost\u003e/offers  \n          - GET \u003cHost\u003e/adjustments  \n          - POST \u003cHost\u003e/user-presentment/access-tokens  \n          - GET \u003cHost\u003e/user-presentment/offers  \n          - GET \u003cHost\u003e/user-presentment/offers/{offer_id}  \n          - POST \u003cHost\u003e/user-presentment/offers/filters  \n          - GET \u003cHost\u003e/user-presentment/offer-ratings  \n          - GET \u003cHost\u003e/user-presentment/offer-ratings/{offer_id}  \n          - POST \u003cHost\u003e/user-presentment/offer-ratings/{offer_id}/likes  \n          - POST \u003cHost\u003e/user-presentment/activations  \n          - GET \u003cHost\u003e/user-presentment/savings  \n          - GET \u003cHost\u003e/user-presentment/adjustments\n          - GET \u003cHost\u003e/platform-admin/offers\n          - POST \u003cHost\u003e/platform-admin/offers/filters\n          - GET \u003cHost\u003e/platform-admin/adjustments\n        - For more information about above endpoints, please refer `PersonalizedOffersController.java` from `src/main/java/com/mastercard/developer/controller` folder.\n    \n## Service Documentation \u003ca name=\"service-documentation\"\u003e\u003c/a\u003e\n\nPersonalized Offers service documentation can be found \n[here](https://developer.mastercard.com/product/personalized-offers)    \n    \n## API Reference \u003ca name=\"api-reference\"\u003e\u003c/a\u003e\n\nThe API Reference can be found [here](https://developer.mastercard.com/pclo-presentment/documentation/api-reference/user-presentment/)\n\n## Support \u003ca name=\"support\"\u003e\u003c/a\u003e\n\nPlease email [pclo_product@mastercard.com]() with any questions or feedback you may have.\n\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\nCopyright 2024 Mastercard\n \nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with \nthe License. You may obtain a copy of the License at:\n \n       http://www.apache.org/licenses/LICENSE-2.0\n \nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on \nan \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the \nspecific language governing permissions and limitations under the License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fpersonalized-offers-reference-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Fpersonalized-offers-reference-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fpersonalized-offers-reference-app/lists"}