# Reference App
source: https://developer.mastercard.com/donations/documentation/reference_app/index.md

We have created a reference application (Java) that demonstrates how to connect \& call various Donate APIs.

In reference application, we demonstrated below major use cases.

1. Register User as a Donor
2. Add a card of Donor to make future Donations without specifying card details againPayment, Retrieve payment and Cancel payment
3. Make a one-time donation using added card
4. Make a guest donation (Anonymous) without adding card or creating user profile on platform
5. Setup a Monthly donation using already added card
6. Setup a Micro donation using already added card
7. View history of donations made
8. Store external donation record
9. Retrieve donation transaction status
10. Processing Micro/Roundup donations with non-Mastercard brand cards

### Prerequisite {#prerequisite}

> To call the Donate APIs in the sandbox environment, use the sandbox keys generated when you created a new project using the steps mentioned on [Generate credentials and create a Sandbox Project](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md#generate-credentials-and-create-a-sandbox-project) section in the [Quick Start Guide](https://developer.mastercard.com/donations/documentation/quick-start-guide/index.md).

### Software Requirements {#software-requirements}

* Java 17 and above
* Gradle 8.2
* Set up the JAVA_HOME environment variable to match the location of your Java installation.

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

* Download and Open the project donationplatform-ref-app and download the required Gradle dependencies
* If you are using IDE, then Select donationplatform-ref-app from Gradle window, then select Tasks, and run 'Clean' and 'Build'
* If you are using command prompt / terminal, Simply go to project folder 'donationplatform-ref-app' and run gradle clean build -x test

This should pull / refresh dependencies and build a project. Note : Do not execute Unit test cases, as we are going to execute that to understand different User journeys in next section.

### Execute use cases in IDE {#execute-use-cases-in-ide}

* Go to \[project folder\]\\src\\test\\java\\com\\mastercard\\donationplatformrefapp, Open MainTest.java file
* Right click on any method (as per API) in the class and run. (Please note that API test execution order matters and should be executed in same order as mentioned below)
* Use cases will execute as per properties defined in donation-api.properties.

### Reference Application Code {#reference-application-code}

This reference application illustrates connecting to the Donation Platform's Sandbox Environment APIs. You can download and understand the endpoints how they operate together by running the test cases.
> Download the reference application, Click
> [donationplatform-ref-app.zip](https://static.developer.mastercard.com/content/donations/referenceapp/donationplatform-ref-app.zip) (146KB)

Once downloaded, Unzip it, Navigate to Project folder `donationplatform-ref-app` and follow README.md file for further instructions.
Note: The Reference Application built is for reference purposes only. Your production application does not need to function the same way.