# Reference Application Tutorial
source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/reference-app-tutorial/index.md

## Overview {#overview}

This tutorial guides you in using the provided reference application to simulate how your API should interact with Ethoca's Merchant Transaction API.

### How It Works {#how-it-works}

The Merchant Transaction API reference application demonstrates the relationship between a merchant API and Ethoca's Merchant Transaction API. You'll use the reference application and the data provided to make calls to the sample merchant API and then return merchant and transaction details.

The reference application uses Postman as the client, which represents Ethoca. It uses Spring MVC as the REST API producer (which represents you, the merchant) to provide an example of how to authenticate, authorize, and process Consumer Clarity requests for looking up transactions.

The reference application runs on context-path `merchant-simulator` and listens for requests on port `9090`. You can edit both configurations in the `application.yml` file.

### What You Need {#what-you-need}

* [JDK 17](http://java.oracle.com)
* [Apache Maven](http://maven.apache.org)
* [Postman](https://www.postman.com/) or your preferred IDE
* [The reference application source file](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/uploads/merchant-api-demo.zip)

## Step-By-Step Run Guide {#step-by-step-run-guide}

Follow these steps to download, unpack, and run the reference application.

1. Access the source code for this tutorial from [this zip file](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/uploads/merchant-api-demo.zip) and unpack it to the local system where you'll run the reference application.
2. In your IDE terminal window, navigate to the source file location of the unpacked zip file.
3. Run the following command.

       mvn spring-boot:run

   The reference application opens ready to use and includes a Postman collection that shows different types of transaction requests that you might receive from us.
4. Choose a sample request to run. Observe the response that is returned and see how it corresponds with the request you selected. You can repeat this step for any of the provided sample requests.

## HMAC Key ID {#hmac-key-id}

Typically, when you create your API, you'll also create your own HMAC signature by following the instructions at [How to Create an HMAC Signature](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/how-to-create-hmac-signature/index.md). However, the HMAC key ID for this demo application is already pre-defined on both the client side and the server side. For this sample implementation, refer to `SignatureGenerator`, `HmacServiceImpl` and `HashGeneratorHmacSha1` classes within the reference application source file.

This project demonstrates the different scenarios that your endpoint must handle. In terms of security, the reference application uses the following HMAC implementation logic across its different components.

### HMAC on the Client Side {#hmac-on-the-client-side}

* Collection level

  The `Pre-request Script` tab of `Merchant API Client V4` implements the logic common across all orders endpoint requests for building and encrypting the signature that must go in the `Authorization` header of the HTTP request.
* Folder level

  The `Pre-request Script` tab of `Order Endpoint` sets the common variables used by its parent level script, the collection. The `healthchecks` endpoint isn't secured, therefore its folder doesn't have a pre-request script defined.
* Request level

  The `Pre-request Script` tab of each sample request sets the `keyRef` and `keyValue` variables as well as takes the search criteria from the request body for the HMAC signature computation.

### HMAC on the Merchant Side {#hmac-on-the-merchant-side}

This project uses Spring Security to implement the HMAC algorithm on the server side. All the related java classes are in the `com.mastercard.developer.hmac` package. Users, authorization groups, and transactions can be found in the `user-repository.yml`, `authorization-group-repository.yml`, and `transaction-repository.yml`, respectively.

Since Ethoca requests are relatively small, this reference application reads the request body twice, first at the Spring Security level for the HMAC computation, then at the controller level for the request processing. To do so, it caches the request on a Spring Security filter implemented by the classes `CachedBodyFilter`, `CachedBodyHttpServletRequest`, and `CachedBodyServletInputStream`.

## Look Up Transactions {#look-up-transactions}

Since this is just a demonstration, this project doesn't implement any logic for looking up transactions. Instead, all requests that are successfully authenticated and authorized are responded to with a static payload, which can be found in the `mock-json-orders-response.json` file.

Within the Resources folder of the reference application source file, there are other static payloads available for testing with.

## Next Steps {#next-steps}

Check out these other articles for guidance on interacting with the Merchant Transaction API:

* See the [Getting Started](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md#integration-phase) page for more information on how to connect and start testing in a sandbox environment.
* [How to Create an HMAC Signature](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/how-to-create-hmac-signature/index.md) guides you through the process of creating the HMAC signature.
* The [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md) provides information about the fields and values relevant to your specific needs.