# Reference App source: https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/reference-app/index.md ## Overview {#overview} The reference app below is written in Java. When built from source code, it allows you to test the Priceless Platform API from command line. Its usage covers every API endpoint plus an error scenario. ## Technologies Used {#technologies-used} Operating systems supported: * Windows * Unix/Linux * macOS Building the API client library requires: * Java 1.7+ * Maven (3.8.3+) * Gradle (7.2+) - *optional* ## Getting the Source Code {#getting-the-source-code} Download a .zip archive from the link below. [mastercard-benefits-and-experiences-portal-ref-app-java.zip](https://static.developer.mastercard.com/content/mastercard-benefits-and-experiences-portal/uploads/mastercard-benefits-and-experiences-portal-ref-app-java.zip) (535KB) Unpack the file and follow the instructions below. They are also included in the `README.md` file. ## Installation {#installation} To install the API client library to your local Maven repository, navigate to the folder you unpacked in the previous step and run this command: ```shell mvn clean install ``` To deploy it to a remote Maven repository instead, configure the settings of the repository and execute: ```shell mvn clean deploy ``` Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information. #### Maven users {#maven-users} Add this dependency to your project's POM file if it is not already there: ```xml com.acme.app mastercard-api-client 1.0.0 compile ``` #### Gradle users {#gradle-users} Add this dependency to your project's build file: ```groovy repositories { mavenCentral() // Needed if the 'mastercard-api-client' jar has been published to maven central. mavenLocal() // Needed if the 'mastercard-api-client' jar has been published to the local maven repo. } dependencies { implementation "com.acme.app:mastercard-api-client:1.0.0" } ``` #### Others {#others} First generate the JAR by executing: ```shell mvn clean package ``` Then manually install the following JAR files: * `target/mastercard-api-client-1.0.0.jar` * `target/lib/*.jar` ## Configuring the Application {#configuring-the-application} Update the following keys in the `{path to project root}/api_client/src/main/resources/application.properties` file: * `mastercard.benefitsportal.ref.app.consumer.key`: The consumer key for the project you created on the **Mastercard Developers** portal; * `mastercard.benefitsportal.ref.app.keystore.path`: Path to the where you saved your **Sandbox OAUTH Credentials** , that is the \*.p12 file. Consult [How to create a Mastercard Developers project](https://developer.mastercard.com/mastercard-benefits-and-experiences-portal/documentation/tutorials-and-guides/create-a-new-api-project/index.md). * `mastercard.benefitsportal.ref.app.keystore.password`: The password to your **Sandbox OAUTH key**. * `mastercard.benefitsportal.ref.app.keystore.alias`: This is the alias you get with the Sandbox credentials. It is "keystorealias" by default. Example: ```java mastercard.benefitsportal.ref.app.url = https://sandbox.api.mastercard.com/the-portal mastercard.benefitsportal.ref.app.consumer.key = Abcdfefgjhilklmnopqrstuvwxyz-dxcq_zD7IiPa0df175e!22a7fddba56e800000000000000000 mastercard.benefitsportal.ref.app.keystore.path = /home/myproject/secure/SandboxKey.p12 mastercard.benefitsportal.ref.app.keystore.password = pwd mastercard.benefitsportal.ref.app.keystore.alias = keystorealias ``` If you run this on a Windows system, make sure to use double backslashes in the path: `mastercard.benefitsportal.ref.app.keystore.path = C:\\path\\SandboxKey.p12` Do a clean build either through an IDE or the command-line interface (CLI). If you are using CLI, navigate to the project root directory (the one that contains the POM file) and run this command: ```shell mvn clean install ``` ## Running the Application from Command Line {#running-the-application-from-command-line} `java -jar {path to the Jar}/mastercard-api-client-1.0.0.jar {argument}` where `argument` is an argument that defines the type of action you want to perform. You can choose from the following arguments: | **Argument** | **Description** | **Relevant Endpoint** | |---------------------------|-------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `benefitsSearch` | Search benefits by credit card number | `/benefits/searches` | | `selectBenefits` | Select benefits that the cardholder is entitled to | `/benefit-selections` | | `benefitRegPanCancel` | Cancel the cardholder's benefit registration | `/benefit-registrations/{partner_uuid}/cancellations` | | `benefitRegPanReplace` | Replace the card number used for selecting benefits with a new number | `/benefit-registrations/{partner_uuid}/credit-cards` | | `benefitRegProfileUpdate` | Update the cardholder's email address and preferred language | `/benefit-registrations/{partner_uuid}/profiles` | | `productSearch` | Get a list of products mapped to this partner | `/products` | | `productInfo` | Get extended information about an individual product | This argument will make the app call two endpoints in succession: * `/products` - to get the list of available products; * `/products/{product_id}` - to get the information about the first `productId` in the list. | | `productInventory` | Get the stock count for the specified product. | This argument will make the app call two endpoints in succession: * `/products` - to get the list of available products; * `/products/{product_id}/inventories` - to check the remaining stock of the first `productId` in the list. | | `productTranslations` | Get the list of languages in which the product content is available | This argument will make the app call two endpoints in succession: * `/products` - to get the list of available products; * `/products/{product_id}/translations` - to get the list of languages into which the first `productId` in the list is translated. | | `orderPlacement` | Place an order for a Priceless product | `/orders` | | `orderStatus` | Returns the status of an individual order | `/orders/{order_id}/statuses` | | `locations` | Get the list of geographical locations in which at least one product is available | `/locations` | | `languages` | Get the list of languages into which at least one of the partner's products has been translated | `/languages` | | `categories` | Get the list of product categories where at least one product is available | `/categories` | | `programs` | Get the list of Mastercard programs | `/programs` | | `health` | Get the health status of the API | `/health-checks` | | `ssoToken` | Get an access token that can be used in a webview session to select benefits | `/user-tokens` | | `errors` | Returns all possible error scenario examples | N/A | Command-line example to run the application: `java -jar target/mastercard-api-client-1.0.0.jar productInfo` In this example, the application returns a sample payload for the `/products/{product_id}` endpoint only. If you want to return payloads from multiple endpoints using one command, then specify the arguments separated with a comma, e.g: `java -jar target/mastercard-api-client-1.0.0.jar ssoToken,benefitsSearch,selectBenefits` In the example above, three actions will be executed: 1. Create an access token. 2. Search for benefits. 3. Select benefits. You can remove the argument from the command line to run all actions at once, for example: `java -jar target/mastercard-api-client-1.0.0.jar`. If you want to execute the actions one by one, you need to call the command with the appropriate argument one after another. Client libraries can be generated for a simplified integration with the reference service, [see more details here](https://developer.mastercard.com/blog/consuming-mastercard-apis-in-client-applications).