# Quick Start Guide
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/quick-start-guide/index.md

## Get Started with the Ethoca Alerts for Merchants APIs {#get-started-with-the-ethoca-alerts-for-merchants-apis}

Use this quick start guide to create a Sandbox project, generate OAuth credentials, make a first API call, and prepare for production onboarding.
Note: We recommend using Open API generator to integrate with APIs. See [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) for more information.

## Prerequisites {#prerequisites}

Before you begin, make sure you have:

* A [Mastercard Developers account](https://developer.mastercard.com/dashboard)
* Access to the Ethoca Alerts Merchant API product in Mastercard Developers
* An environment that can store a `.p12` keystore securely
* An HTTP client or generated SDK that can sign requests with OAuth 1.0a
* A plan for your integration model: Push webhook delivery, Pull retrieval, or both

## 1. Create a Sandbox project {#1-create-a-sandbox-project}

1. Go to your [dashboard](https://developer.mastercard.com/dashboard).
2. Select **Create New Project** from the upper right.
3. In the dropdown list, select **Ethoca Alerts Merchant API**.
4. After you've made your choices, select **Continue**.
5. Enter a name for your project. You can also choose to invite other team members to view and work on your project.
6. Select **Continue**.

## 2. Generate Sandbox credentials {#2-generate-sandbox-credentials}

The Mastercard-hosted Alerts for Merchants APIs use OAuth 1.0a.

1. Select **Download PKCS#12 Keystore** to download a zip file containing the .p12 file required for OAuth authentication in Sandbox.
2. After download completes, select **Continue**.
3. Enter a keyalias and keystore password for each area and make a note for use later. The keystore password is used in conjunction with the .p12 file and Client ID for OAuth authentication.
4. Select **Confirm and Continue** to complete the Sandbox Setup process.

Your project page also shows the consumer key for the environment. The consumer key format is `<client_id>!<key_id>`. You use that value with the signing key from the `.p12` file to generate OAuth 1.0a request signatures.

For implementation details, see [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/).

## 3. Configure authentication {#3-configure-authentication}

Open the zip file you downloaded and import the Sandbox `.p12` file into your application or local keystore workflow.

At minimum, your integration needs these values:

* Consumer key
* `.p12` keystore file
* Key alias
* Keystore password
* Sandbox base URL for the API you are calling

For a working Java example, see the [Reference Application Tutorial](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/reference-app-tutorial/index.md).

## 4. Generate an API client {#4-generate-an-api-client}

Download the relevant OpenAPI specification and generate a client, or use the specification directly with your preferred HTTP tooling.

* Pull API: [alert-delivery-outcome-specs_inbound.yaml](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alert-delivery-outcome-specs_inbound.yaml) (35KB)
* Outcome API: [alert-delivery-outcome-specs_inbound.yaml](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alert-delivery-outcome-specs_inbound.yaml) (35KB)
* Push API payload contract: [alerts-push-conflicts-notification-specs-outbound.yaml](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alerts-push-conflicts-notification-specs-outbound.yaml) (32KB)

If you want the fastest path to a first successful call, start with the Pull API because it lets you validate OAuth signing and response handling without first exposing a webhook endpoint.

## 5. Test the Sandbox {#5-test-the-sandbox}

For a first end-to-end validation, call the Pull API in Sandbox and retrieve one customer dispute alert.

Base URL:

```text
https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants
```

Example request:

```bash
curl --request GET \
	--url 'https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants/alerts?alert_type=CUSTOMERDISPUTE&size=1' \
	--header 'Authorization: OAuth oauth_consumer_key="<consumer-key>", oauth_signature_method="RSA-SHA1", oauth_timestamp="<timestamp>", oauth_nonce="<nonce>", oauth_version="1.0", oauth_signature="<signature>"' \
	--header 'Accept: application/json'
```

Expected response:

```json
{
	"alerts": [
		{
			"alertId": "3EAKPL9SX735ZI9PII18FPQZL",
			"alertTimestamp": "2026-01-12T06:15:13.171792Z",
			"merchantId": "d61391c1-b958-45a3-92ed-bd356cbb8237",
			"merchantName": "submerchant1",
			"alertType": "CUSTOMERDISPUTE",
			"provider": {
				"issuerName": "sample name",
				"source": "issuer"
			},
			"transaction": {
				"authorizationCode": "3421"
			}
		}
	]
}
```

This sample is based on the documented Sandbox test data in [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md). After you successfully retrieve an alert, continue by testing `POST /alerts/acknowledges` and then `POST /outcomes`.

## 6. Complete service-specific onboarding {#6-complete-service-specific-onboarding}

Alerts for Merchants requires service onboarding beyond creating API keys.

* For **Push** integrations, you must expose an HTTPS webhook endpoint and register that endpoint with Ethoca so alerts can be delivered to your system.
* For **Pull** integrations, your merchant setup must be configured for Pull retrieval.
* For Sandbox test templates and coordinated validation, contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com).

Customer Delivery also supports the readiness checks required before production launch, including alert delivery, alert matching, and outcome submission validation.

## 7. Promote to Production {#7-promote-to-production}

When your Sandbox testing is complete, request Production access for your project.

1. Contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com).
2. Submit the requested onboarding information, including your customer contact details and any integration-specific setup required for your chosen model.
3. For Push integrations, confirm the Production webhook endpoint and certificate trust requirements.
4. Wait for Mastercard approval and Production enablement.

Approval typically takes two to five days, depending on the terms of your contract.

## Next Steps {#next-steps}

1. Use the [Reference Application Tutorial](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/reference-app-tutorial/index.md) if you want a working Java example.
2. Review [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md) for additional Sandbox scenarios and expected responses.
3. Explore the [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-reference/index.md) for the full request and response schema for each endpoint.