# Reference App
source: https://developer.mastercard.com/mastercard-send-person-to-person/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 Payment Transfer API in different [environments](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/api-basics/index.md#environments): Sandbox, Mastercard Test Facility (MTF), and Production. It provides API Client capabilities with OAuth 1.0a 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/mastercard-send-person-to-person/documentation/img/payment-transfer-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 Send** 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 [Getting Started with the APIs](https://developer.mastercard.com/mastercard-send/documentation/implementation/getting-started/).   
  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/mastercard-send-person-to-person/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 [Good to Know](https://developer.mastercard.com/mastercard-send-person-to-person/documentation/index.md#good-to-know).

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

Download
[send-person-to-person-reference-app.zip](https://static.developer.mastercard.com/content/mastercard-send-person-to-person/uploads/send-person-to-person-reference-app.zip) (780KB) 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/mastercard-send-person-to-person/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 and update the file name in the `./src/main/resources/application.properties` file for the `signing.pkcs12KeyFile=` property.
2. Using the signing key details obtained from Mastercard Developers, update the `./src/main/resources/application.properties` file for the `signing.keyAlias`, `signing.keyPassword`, `signing.consumerKey ` properties.

### 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:
[send-payment-transfer-api-swagger.yaml](https://static.developer.mastercard.com/content/mastercard-send-person-to-person/swagger/send-payment-transfer-api-swagger.yaml) (138KB)

The latest API specification is also available in the [API Reference](https://developer.mastercard.com/mastercard-send-person-to-person/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/mastercard-send-person-to-person/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/mastercard-send-person-to-person/documentation/img/payment-transfer-ref-app1.png)

##### Create payment transfer {#create-payment-transfer}

Click **Create Payment Transfer** to access the POST 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/mastercard-send-person-to-person/documentation/img/payment-transfer-ref-app2.png)

Click **Submit** to call the API using the form values. You can view the request and response objects below the form, as shown below.

![](https://static.developer.mastercard.com/content/mastercard-send-person-to-person/documentation/img/payment-transfer-ref-app3.png)

##### Retrieve transfer details {#retrieve-transfer-details}

Click **Get by ID** or **Get by Reference** to access the required GET API request form. Depending on the form, provide the Transfer ID or Reference from a previous successful POST API response and click **Submit** to retrieve those details, as shown below. If you made a POST API call with this reference application, the form will already show that Transfer ID or Reference value.

![](https://static.developer.mastercard.com/content/mastercard-send-person-to-person/documentation/img/payment-transfer-ref-app4.png)