# Reference App
source: https://developer.mastercard.com/account-validation/documentation/reference-app/index.md

## Overview {#overview}

This is a simple Open API and Java Spring Boot application that shows how to integrate with the Account Validation API in different [environments](https://developer.mastercard.com/account-validation/documentation/api-basics/index.md#environments): Sandbox, Mastercard Test Facility (MTF), and Production. It provides API Client capabilities with OAuth 1.0a and JSON Web Encryption (JWE) based encryption/decryption for accessing the API endpoint.
You can run the reference application through your command prompt or terminal without running any Integrated Development Environment (IDE). You can use your preferred IDE to go through the source code and check the workflow.

![](https://static.developer.mastercard.com/content/account-validation/documentation/images/av-ref-app-overview.png)

###### What you will learn {#what-you-will-learn}

* How to build and use the reference application.
* How to configure the application for the Sandbox, MTF, and Production environments.

## Prerequisites {#prerequisites}

* [Java 11+](https://www.java.com/en/download/manual.jsp). Ensure that your `JAVA_HOME` environment variable is pointing to your JDK installation or have the Java executable on your `PATH` environment variable.
* [Maven 3.6.0+](https://maven.apache.org/download.cgi)
* IDE of your choice, for example, Eclipse, IntelliJ IDEA, or VS Code.
* If your organization uses internal artifact repositories for obtaining dependencies, refer to this [documentation](https://maven.apache.org/guides/mini/guide-multiple-repositories.html) to ensure that your dependencies are set up.
* A Mastercard Developers [project](https://developer.mastercard.com/dashboard) created with the **Mastercard Account Validation** API service. This generated the Sandbox keys and credentials that are required to use the Sandbox and MTF environments. For guidance on creating a project, see the [quick start guide](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/quick-start-guide/).   
  After successful MTF testing, you set up your Production keys by requesting Production access for your project in your [Developer Dashboard](https://developer.mastercard.com/dashboard) project page.
* To use the APIs in the MTF and Production environments, you must [register](https://developer.mastercard.com/mastercard-send/documentation/send-eligibility/) as a Mastercard Send Program Participant. Your [Mastercard representative](https://developer.mastercard.com/account-validation/documentation/support/index.md) can help you with this process, during which you will be given the Partner Reference IDs for use in your API calls to those environments.   
  You must also be set up for those environments, which requires you to provide your Consumer Key to your Mastercard Delivery Manager, see [Client authentication](https://developer.mastercard.com/account-validation/documentation/api-basics/index.md#client-authentication).

## Get the Source Code {#get-the-source-code}

Download
[av-reference-app.zip](https://static.developer.mastercard.com/content/account-validation/uploads/av-reference-app.zip) (2MB) and open it in your IDE. The root directory of the application includes README.md and CHANGELOG.md files, which provide further information about the application.

Instructions for configuring and running the application are provided below.

## Setup {#setup}

The following steps use the keys and details that are downloaded or provided when creating your Mastercard Developers project. Some items are available on your Developer Dashboard project page after project setup. For more information about the keys, see [API Basics](https://developer.mastercard.com/account-validation/documentation/api-basics/index.md).

### Configure signing keys {#configure-signing-keys}

Signing keys are used to generate Authorization headers, which Mastercard uses to authenticate your API requests.

1. Copy the downloaded .p12 file to the `./src/main/resources` path.

2. Update these properties in the `./src/main/resources/application.properties` file:

   * `signing.pkcs12KeyFile=` = The signing key file name
   * `signing.keyAlias`, `signing.keyPassword`, `signing.consumerKey` = The signing key details obtained from Mastercard Developers

### Enable encryption {#enable-encryption}

The MTF and Production environments support optional payload encryption --- to use payload encryption, you must request it when Mastercard onboards your configuration preferences. Sandbox does not support payload encryption.

To enable or disable encryption/decryption for your requests and responses, update the `client.encryption.enabled` property to either true or false in the `./src/main/resources/application.properties` file.

To use encryption/decryption, you must configure the encryption keys:

1. Copy these files to the `./src/main/resources` path:

   * Client Encryption Key certificate .pem file
   * Mastercard Encryption Key .p12 file
2. Update these properties in the `./src/main/resources/application.properties` file:

   * `client.encryption.certificate=` = The Client Encryption Key certificate file name
   * `mastercard.encryption.pkcs12KeyFile=` = The Mastercard Encryption Key file name
   * `mastercard.encryption.keyAlias=` and `mastercard.encryption.keyPassword=` = The Mastercard Encryption Key details

Client Encryption Keys are used to encrypt the request payload sent by you. Mastercard Encryption Keys are used to decrypt the response payload returned by Mastercard. Remember that the MTF and Production environments use different sets of keys.

### Configure partner details {#configure-partner-details}

To use the APIs in the MTF and Production environments, update the `partnerId=` parameter in the `./src/main/resources/application.properties` file to match your Partner Reference ID.

### Use the latest API specification {#use-the-latest-api-specification}

You can directly run the application with the API specification (YAML) file included in the reference application. This reference application includes the API specification that was available at the time of preparing this application.

If there is a newer version of the API specification, you can download the YAML file using this link and add it to your `./src/main/resources/specifications` directory:
[account-validation-api-swagger.yaml](https://static.developer.mastercard.com/content/account-validation/swagger/account-validation-api-swagger.yaml) (29KB)

The latest API specification is also available in the [API Reference](https://developer.mastercard.com/account-validation/documentation/api-reference/index.md) page.

### Switch between environments {#switch-between-environments}

By default, the application will use the Sandbox API. You can switch between Sandbox, MTF, and Production environments by updating the `environment` property in the `./src/main/resources/application.properties` file. This table shows the value to use for each environment:

| Environment |          Value           |
|-------------|--------------------------|
| Sandbox     | `environment=sandbox`    |
| MTF         | `environment=mtf`        |
| Production  | `environment=production` |

When you change environment, remember that you might need to adjust the keys and properties as per the instructions above.

### Change server port {#change-server-port}

The server port is configured to 8080. To change the server port, update the `server.port=` property in the `./src/main/resources/application.properties` file.

If you update the default port, you must update the `const SERVER_URL` property path in the
`./src/main/resources/static/assets/js/environment.js` file.

## Build and Run {#build-and-run}

If you have Maven installed (as per the [Prerequisites](https://developer.mastercard.com/account-validation/documentation/reference-app/index.md#prerequisites)), you can build and run the code using
the following command:

    mvn spring-boot:run

In your web browser, access the reference application by visiting `localhost:8080` (or change the port number accordingly).

### Use the application {#use-the-application}

When you start the reference application, you will see the following screen in your web browser.

![](https://static.developer.mastercard.com/content/account-validation/documentation/images/av-ref-app1.png)

Click **Account Validation** to access the API request form, shown below. For convenience, the form is pre-populated with a functioning request for Sandbox, but you can change the values and submit the form.

![](https://static.developer.mastercard.com/content/account-validation/documentation/images/av-ref-app2.png)

Click **Validate Account** to submit the form and call the API. You can view the request and response objects below the form, as shown below.

![](https://static.developer.mastercard.com/content/account-validation/documentation/images/av-ref-app3.png)