{"id":28577483,"url":"https://github.com/mastercard/promotions-digital-enablement-reference-app","last_synced_at":"2025-06-11T00:38:50.366Z","repository":{"id":45353348,"uuid":"458238319","full_name":"Mastercard/promotions-digital-enablement-reference-app","owner":"Mastercard","description":"Demonstrates how clients can consume Promotions Digital Enablement API which support different promotions activities to Mastercard Network.","archived":false,"fork":false,"pushed_at":"2025-04-30T20:40:08.000Z","size":140,"stargazers_count":1,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-30T21:36:44.312Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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,"zenodo":null}},"created_at":"2022-02-11T15:22:31.000Z","updated_at":"2025-04-30T20:40:13.000Z","dependencies_parsed_at":"2025-02-10T18:20:20.621Z","dependency_job_id":"7d669dde-2271-41f2-8452-80c2e002c69f","html_url":"https://github.com/Mastercard/promotions-digital-enablement-reference-app","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpromotions-digital-enablement-reference-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpromotions-digital-enablement-reference-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpromotions-digital-enablement-reference-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpromotions-digital-enablement-reference-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mastercard","download_url":"https://codeload.github.com/Mastercard/promotions-digital-enablement-reference-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mastercard%2Fpromotions-digital-enablement-reference-app/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259177332,"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:37:55.792Z","updated_at":"2025-06-11T00:38:50.346Z","avatar_url":"https://github.com/Mastercard.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reference Implementation for Mastercard Promotions Digital Enablement\n\n[![](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/Mastercard/promotions-digital-enablement-reference-app/blob/master/LICENSE)\n\n## Table of Contents\n- [Overview](#overview)\n  * [Compatibility](#compatibility)\n  * [References](#references)\n- [Usage](#usage)\n  * [Prerequisites](#prerequisites)\n  * [Configuration](#configuration)\n  * [Integrating with OpenAPI Generator](#integrating-with-openapi-generator)\n  * [Build and Execute](#build-and-execute)\n- [Use Cases](#use-cases)\n- [API Reference](#api-reference)\n  * [Authorization](#authorization)\n  * [Encryption and Decryption](#encryption-and-decryption)\n    - [Loading Encryption Certificate](#loading-encryption-certificate)\n    - [Loading Decryption Key](#loading-decryption-key)\n    - [Configuring JWE Instance](#configuring-jwe-instance)  \n    - [Encrypting Entire Payloads](#encrypting-entire-payloads)\n    - [Decrypting Entire Payloads](#decrypting-entire-payloads)\n  * [Request Examples](#request-examples)\n  * [Recommendation](#recommendation)\n- [Support](#support)\n- [License](#license)\n\n## Overview \u003ca name=\"overview\"\u003e\u003c/a\u003e\nThis is a reference application to demonstrate how Promotion Digital Enablement API can be used for the supported operations. Please see here for details on the API: [Mastercard Developers](https://developer.mastercard.com/rewards-progress/documentation).\nThis application illustrates connecting to the Promotion Digital Enablement API with encryption. To call these APIs, consumer key, .p12 files and encryption certs are required from your [Mastercard Developers](https://developer.mastercard.com/dashboard) project.\n\n### Compatibility \u003ca name=\"compatibility\"\u003e\u003c/a\u003e\n* [Java 8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) or later\n\n### References \u003ca name=\"references\"\u003e\u003c/a\u003e\n* [Mastercard’s OAuth Signer library](https://github.com/Mastercard/oauth1-signer-java)\n* [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/using-oauth-1a-to-access-mastercard-apis/)\n\n## Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\n### Prerequisites \u003ca name=\"prerequisites\"\u003e\u003c/a\u003e\n* [Mastercard Developers Account](https://developer.mastercard.com/dashboard) with access to Promotion Digital Enablement API\n* A text editor or IDE\n* [Spring Boot 2.2+](https://spring.io/projects/spring-boot)\n* [Apache Maven 3.3+](https://maven.apache.org/download.cgi)\n* Set up the `JAVA_HOME` environment variable to match the location of your Java installation.\n\n### Configuration \u003ca name=\"configuration\"\u003e\u003c/a\u003e\n* Create an account at [Mastercard Developers](https://developer.mastercard.com/account/sign-up).  \n* Create a new project and add `Promotion Digital Enablement` API to your project.   \n* Configure project and download signing key. It will download the zip file.  \n* Select `.p12` files from zip and copy it to `src/main/resources` in the project folder.\n* Open `${project.basedir}/src/main/resources/application.properties` and configure below parameters.\n    \n    \u003e**mastercard.api.base-path=https://sandbox.api.mastercard.com/loyalty/rewards**, its a static field, will be used as a host to make API calls.\n    \n    **Below properties will be required for authentication of API calls.**\n    \n    \u003e**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.\n    \n    \u003e**mastercard.api.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)\n      \n    \u003e**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](https://developer.mastercard.com/dashboard).\n    \n    \u003e**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](https://developer.mastercard.com/dashboard).\n\n    **Below properties will be required to encrypt and decrypt the request and response payloads**\n    \n    \u003e**mastercard.api.encryption-certificate-file=**, this is the path to certificate (.crt or .pem) file. Add classpath for file, after placing it at src\\main\\resources in the project folder. Download Encryption Key from \"Client Encryption\" section on your project page in [Mastercard Developers](https://developer.mastercard.com/dashboard)\n    \n    \u003e**mastercard.api.decryption-key-file=**, this is your private key (.p12) file, required to decrypt a request. Add classpath for this file, after placing it at src\\main\\resources in the project folder.\n    \n    \u003e**mastercard.api.decryption-key-alias=**, this is required to load your decryption private key.\n\n    \u003e**mastercard.api.decryption-keystore-password=**, this is required to load your decryption private key. \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 [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification). \nIt provides generators and library templates for supporting multiple languages and frameworks.\n\nSee also:\n* [OpenAPI Generator (maven Plugin)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin)\n* [OpenAPI Generator (executable)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-cli)\n* [CONFIG OPTIONS for java](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/java.md)\n\n#### OpenAPI Generator Plugin Configuration\n```xml\n\u003c!-- https://mvnrepository.com/artifact/org.openapitools/openapi-generator-maven-plugin --\u003e\n\u003cplugin\u003e\n    \u003cgroupId\u003eorg.openapitools\u003c/groupId\u003e\n    \u003cartifactId\u003eopenapi-generator-maven-plugin\u003c/artifactId\u003e\n    \u003cversion\u003e${openapi-generator.version}\u003c/version\u003e\n    \u003cexecutions\u003e\n        \u003cexecution\u003e\n            \u003cid\u003ePromotions Digital Enablement API Client\u003c/id\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/Promotions_Digital_Enablement-api-spec.yaml\u003c/inputSpec\u003e\n                \u003cgeneratorName\u003ejava\u003c/generatorName\u003e\n                \u003clibrary\u003eokhttp-gson\u003c/library\u003e\n                \u003cgenerateApiTests\u003efalse\u003c/generateApiTests\u003e\n                \u003cgenerateModelTests\u003efalse\u003c/generateModelTests\u003e\n                \u003cconfigOptions\u003e\n                    \u003csourceFolder\u003esrc/gen/java/main\u003c/sourceFolder\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```\n\n#### Generating The API Client Sources\nNow that you have all the dependencies you need, you can generate the sources. To do this, use one of the following two methods:\n\n`Using IDE`\n* **Method 1**\u003cbr/\u003e\n  In IntelliJ IDEA, open the Maven window **(View \u003e Tool Windows \u003e Maven)**. Click the icons `Reimport All Maven Projects` and `Generate Sources and Update Folders for All Projects`\n\n* **Method 2**\u003cbr/\u003e\n  In the same menu, navigate to the commands **({Project name} \u003e Lifecycle)**, select `clean` and `compile` then click the icon `Run Maven Build`. \n\n`Using Terminal`\n* Navigate to the root directory of the project within a terminal window and execute `./mvnw clean compile` command.\n\n### Build and Execute \u003ca name=\"build-and-execute\"\u003e\u003c/a\u003e\nOnce 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\n\n1. Run `mvn clean install` from the root of the project directory.\n2. Run `mvn spring-boot:run` to start the project.\n3. Navigate to [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) in your browser.\n\n## Swagger \u003ca name=\"Swagger\"\u003e\u003c/a\u003e\nNavigate to [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) in your browser to access bellow controllers,\n1. AccountController\n    1. /accounts/searches\n2. OptInController\n    1. /promotion-activations\n    2. /promotions\n3. ProgressController\n    1. /promotion-progresses\n\n## Use Cases \u003ca name=\"use-cases\"\u003e\u003c/a\u003e\nRefer [Use Cases](https://developer.mastercard.com/rewards-progress/documentation/use-cases/) for more details.\n\n## API Reference \u003ca name=\"api-reference\"\u003e\u003c/a\u003e\nRefer [Api Reference](https://developer.mastercard.com/rewards-progress/documentation/api-reference/) To develop a client application that consumes a RESTful Promotion Digital Enablement API with Spring Boot.\n\n### Authorization \u003ca name=\"authorization\"\u003e\u003c/a\u003e\nThe `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.\n\n### Encryption and Decryption \u003ca name=\"encryption-and-decryption\"\u003e\u003c/a\u003e\nThe `com.mastercard.developer.interceptors` provides a class that you can use when configuring your API client. This class will take care of encrypting payload before sending the request and decrypting payload after receiving the response.\n\n#### Loading Encryption Certificate \u003ca name=\"loading-encryption-certificate\"\u003e\u003c/a\u003e\n\nA `Certificate` object can be created from a file by calling `EncryptionUtils.loadEncryptionCertificate`:\n```java\nCertificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(\"\u003cinsert certificate file path\u003e\");\n```\n\nSupported certificate formats: PEM, DER.\n\n#### Loading Decryption Key \u003ca name=\"loading-decryption-key\"\u003e\u003c/a\u003e\n\n##### From a PKCS#12 Key Store\n\nA `PrivateKey` object can be created from a PKCS#12 key store by calling `EncryptionUtils.loadDecryptionKey` the following way:\n```java\nPrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(\n                                    \"\u003cinsert PKCS#12 key file path\u003e\", \n                                    \"\u003cinsert key alias\u003e\", \n                                    \"\u003cinsert key password\u003e\");\n```\n\n#### Configuring JWE Instance \u003ca name=\"configuring-jwe-instance\"\u003e\u003c/a\u003e\nUse the `JweConfigBuilder` to create `JweConfig` instances. Example:\n```java\nJweConfig jweConfig = JweConfigBuilder.aJweEncryptionConfig()\n        .withEncryptionCertificate(certificate)\n        .withEncryptionPath(\"$\", \"$\")\n        .withEncryptedValueFieldName(\"encryptedPayload\")\n        .withDecryptionKey(decryptionKey)\n        .build();\n```\n\n#### Encrypting Entire Payloads \u003ca name=\"encrypting-entire-payloads\"\u003e\u003c/a\u003e\n\nExample using the configuration [above](#configuring-jwe-instance):\n```java\nString payload = \"{\" +\n    \"    \\\"sensitiveField1\\\": \\\"sensitiveValue1\\\",\" +\n    \"    \\\"sensitiveField2\\\": \\\"sensitiveValue2\\\"\" +\n    \"}\";\n```\n\nOutput:\n```json\n{\n    \"encryptedPayload\": \"eyJhbGciOiJSU0EtT0(...)IsImVuYyI6IkEyNTifQ.OKOawDo13gRp2ojaHV7LFpZcg(...)VZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe.48V1_ALb6US04U3b.5eym8TW_c8SuK0ltJ3rpYI(...)7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji.XFBoMYUZodetZdvTiFvSkQ\"\n}\n```\n\n#### Decrypting Entire Payloads \u003ca name=\"decrypting-entire-payloads\"\u003e\u003c/a\u003e\n\nExample using the configuration [above](#configuring-jwe-instance):\n```java\nString encryptedPayload = \"{\" +\n    \"  \\\"encryptedPayload\\\": \\\"eyHhbGciOiJSU0EtT0F(...)BiYzQyTIyNTQ1ODgzNSJ9.VkO7N6gAptqoD7IQaK(...)ptYySP_TuvERby89DY1EezAm3A.qj6ISyzq1ASDJKD0.ENF7bUfBkoWAEYvk(...)o9JGMctx-PSdeVqwCQAVRNj0pYs1WjOp4UDbE4eEZIF6YA.Wc7ARH7R6sikpKzxET3MYA\\\" +\n    \"}\";\n```\n\nOutput:\n```json\n{\n    \"sensitiveField1\": \"sensitiveValue1\",\n    \"sensitiveField2\": \"sensitiveValue2\"\n}\n```\n\n### Recommendation \u003ca name=\"recommendation\"\u003e\u003c/a\u003e\nIt is recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.\n\n## Support \u003ca name=\"support\"\u003e\u003c/a\u003e\nIf you would like further information, please send an email to apisupport@mastercard.com\n\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\nCopyright 2020 Mastercard\n \nLicensed 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\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 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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fpromotions-digital-enablement-reference-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastercard%2Fpromotions-digital-enablement-reference-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastercard%2Fpromotions-digital-enablement-reference-app/lists"}