# Reference Application
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/reference-app/index.md

The Ethoca Alerts for Merchants Reference Application is a complete end-to-end implementation demonstrating pull-based alert retrieval, acknowledgement submission, and outcome reporting. You can use it as a learning resource or as a foundation for your own integration.

*** ** * ** ***

## Overview {#overview}

The Reference Application implements the following workflow:

1. **Retrieve Alerts** --- Calls `GET /alerts` to fetch unacknowledged alerts from Sandbox
2. **Parse Alert Data** --- Deserializes alert JSON and displays key fields
3. **Acknowledge Receipt** --- Calls `POST /alerts/acknowledges` to confirm alert receipt
4. **Submit Outcomes** --- Calls `POST /outcomes` to report investigation results
5. **Error Handling** --- Demonstrates retry logic, error interpretation, and logging

*** ** * ** ***

## Source Code {#source-code}

**Repository:** <https://github.com/ethoca/alerts-for-merchants-reference-app>

**Language:** Java (Spring Boot)

**Key Components:**

* OAuth 1.0a authentication integration using `mastercard-java-sdk`
* REST client for all three APIs (Pull, Acknowledgement, Outcome)
* Batch processing for multiple alerts
* Error handling with retry logic and detailed logging
* Configuration management for Sandbox and Production environments

*** ** * ** ***

## Setup Instructions {#setup-instructions}

### Prerequisites {#prerequisites}

* Java 11 or later
* Maven 3.6+
* Ethoca Sandbox credentials (consumer key and `.p12` keystore)

### Step 1: Clone the Repository {#step-1-clone-the-repository}

```bash
git clone https://github.com/ethoca/alerts-for-merchants-reference-app.git
cd alerts-for-merchants-reference-app
```

### Step 2: Configure Credentials {#step-2-configure-credentials}

Create a `config.properties` file in the project root with your Sandbox credentials:

```properties
# OAuth Configuration
oauth.consumer.key=YOUR_CONSUMER_KEY
oauth.keystore.path=/path/to/your/keystore.p12
oauth.keystore.password=YOUR_KEYSTORE_PASSWORD
oauth.keystore.alias=YOUR_KEY_ALIAS

# Environment Configuration
api.base.url=https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants
api.environment=SANDBOX
```

Alternatively, set these as environment variables:

```bash
export OAUTH_CONSUMER_KEY=YOUR_CONSUMER_KEY
export OAUTH_KEYSTORE_PATH=/path/to/your/keystore.p12
export OAUTH_KEYSTORE_PASSWORD=YOUR_KEYSTORE_PASSWORD
export API_BASE_URL=https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants
```

### Step 3: Build the Application {#step-3-build-the-application}

```bash
mvn clean install
```

### Step 4: Run the Application {#step-4-run-the-application}

```bash
mvn spring-boot:run
```

The application will start a REST API on `http://localhost:8080` with the following endpoints:

* `GET /alerts` --- Retrieve alerts from Sandbox
* `POST /alerts/acknowledges` --- Acknowledge alerts
* `POST /outcomes` --- Submit outcomes

### Step 5: Test an Endpoint {#step-5-test-an-endpoint}

Retrieve alerts:

```bash
curl -X GET http://localhost:8080/alerts \
  -H "Content-Type: application/json" \
  -d '{"alert_type":"CUSTOMERDISPUTE","size":1}'
```

*** ** * ** ***

## Key Integration Patterns {#key-integration-patterns}

### OAuth 1.0a Authentication {#oauth-10a-authentication}

The reference app uses the `mastercard-java-sdk` to handle OAuth 1.0a signature generation:

```java
// OAuth configuration
OAuthConfiguration config = new OAuthConfiguration(
  consumerKey,
  keystorePath,
  keystorePassword,
  keystoreAlias
);

// Client creation
HttpClient client = new HttpClient(config);

// Authenticated request
HttpResponse response = client.execute(
  new HttpGet("https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants/alerts")
);
```

### Error Handling and Retries {#error-handling-and-retries}

The app implements exponential backoff for recoverable errors:

```java
// Check Recoverable flag
if (error.isRecoverable()) {
  // Retry with exponential backoff
  Thread.sleep(backoffMs);
} else {
  // Log and fail permanently
  logger.error("Permanent error: " + error.getDescription());
}
```

### Batch Processing {#batch-processing}

Efficiently process multiple alerts:

```java
// Retrieve alerts
List<Alert> alerts = client.getAlerts(filter);

// Acknowledge all
List<Acknowledgement> acks = alerts.stream()
  .map(a -> new Acknowledgement(a.getAlertId(), "SUCCESS"))
  .collect(Collectors.toList());
client.acknowledgeAlerts(acks);
```

*** ** * ** ***

## Adapting to Your Tech Stack {#adapting-to-your-tech-stack}

The reference app demonstrates patterns that are portable to other languages and frameworks:

**Node.js/TypeScript:**

* Use the `oauth-1.0a` npm package for signature generation
* Use `axios` or `node-fetch` for HTTP requests

**Python:**

* Use the `requests-oauthlib` library for OAuth 1.0a
* Use `requests` for HTTP calls

**Go:**

* Use `github.com/mrjones/oauth` for OAuth 1.0a
* Use `net/http` for HTTP requests

Refer to the Reference Application source for the complete implementation pattern and adapt it to your language.

*** ** * ** ***

## Running in Production {#running-in-production}

Before going to production, configure the app with Production credentials and base URL:

```bash
export OAUTH_CONSUMER_KEY=YOUR_PRODUCTION_KEY
export API_BASE_URL=https://api.ethocaweb.com/ethoca/alerts/merchants
```

Test in your staging environment first, then deploy to production.

*** ** * ** ***

## Troubleshooting {#troubleshooting}

**401 Unauthorized:** Verify that your consumer key and keystore are correct. See [Support -- 401 Errors](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/support/index.md#why-am-i-getting-a-401-unauthorized-error).

**Connection Refused:** Confirm that the API base URL is correct and that your network allows outbound HTTPS connections.

**Empty Alert List:** Ensure that alerts have been submitted to Sandbox and that your date range filter is correct. See [Support -- How do I retrieve alerts?](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/support/index.md#how-do-i-retrieve-alerts-using-the-pull-api).

*** ** * ** ***

## Next Steps {#next-steps}

* Review the [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/tutorials-and-guides/quick-start-guide.md) for step-by-step setup
* See [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/testing/index.md) for comprehensive test cases
* Check [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/code-and-formats/index.md) for error reference
* Refer to the [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/api-reference/index.md) for endpoint details