# API Reference
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-reference/index.md

## Ethoca Alerts for Merchants API Reference {#ethoca-alerts-for-merchants-api-reference}

The Ethoca Alerts for Merchants API consists of three distinct services that work together to deliver alerts, retrieve them, and submit investigation outcomes. This page provides environment URLs, comprehensive endpoint documentation, and downloadable OpenAPI specifications.

*** ** * ** ***

## Environments {#environments}

The API is available in the following environments:

|  Environment   |                          Base URL                           |
|----------------|-------------------------------------------------------------|
| **Sandbox**    | `https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants` |
| **Production** | `https://api.ethocaweb.com/ethoca/alerts/merchants`         |

Use the **Sandbox** environment for development and testing. Switch to **Production** only after completing Sandbox validation and receiving production credentials from your Ethoca Customer Delivery Team.

*** ** * ** ***

## API Services {#api-services}

Ethoca Alerts for Merchants provides three complementary services:

### 1. Pull API --- Retrieve and Acknowledge Alerts {#1-pull-api--retrieve-and-acknowledge-alerts}

Merchants use this API to retrieve alerts from Ethoca on a schedule and acknowledge receipt.

**Endpoints:**

* `GET /alerts` --- Retrieve unacknowledged alerts with optional filtering
* `POST /alerts/acknowledges` --- Acknowledge Retrieved Alerts

**Use this if:** You prefer polling over webhooks, or need batch retrieval on your own schedule.

**OpenAPI Specification:**

* Download: [alerts-delivery-pull-api-spec.yaml](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alert-delivery-outcome-specs_inbound.yaml)


API Specification: `https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alert-delivery-outcome-specs_inbound.yaml`

*** ** * ** ***

### 2. Push API --- Receive Alerts via Webhook {#2-push-api--receive-alerts-via-webhook}

Ethoca pushes alerts to your webhook endpoint in real-time as they are created.

**Endpoints:**

* `POST /webhook (Inbound)` --- Ethoca sends alerts to your registered webhook URL
* Your endpoint must return HTTP 200 OK with acknowledgement status

**Use this if:** You want real-time notification of alerts and can expose a public HTTPS endpoint.

**WebHook Contract:**

* Ethoca calls your registered HTTPS endpoint with alert payload
* Your endpoint processes the alert and returns acknowledgement in response body
* Ethoca retries failed deliveries with exponential backoff

**OpenAPI Specification:**

* Download: [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)


API Specification: `https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alerts-push-conflicts-notification-specs-outbound.yaml`

*** ** * ** ***

### 3. Outcome API --- Submit Investigation Results {#3-outcome-api--submit-investigation-results}

After investigating an alert (via Pull or Push), merchants submit outcomes back to Ethoca for transmission to card issuers.

**Endpoints:**

* `POST /outcomes` --- Submit investigation results with outcome codes and refund information

**Use this:** Immediately after investigation completion, within 24 hours of alert receipt when possible.

**Outcome Information:**

* Alert ID and alert type (Confirmed Fraud or Customer Dispute)
* Investigation outcome code (for example, `RESOLVED`, `STOPPED`, `NOT_FOUND`)
* Refund information (refund status, type, amount if applicable)
* Comments and investigation notes

**OpenAPI Specification:**

* Download: [alert-delivery-outcome-specs_inbound.yaml](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alert-delivery-outcome-specs_inbound.yaml)


API Specification: `https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/swagger/alert-delivery-outcome-specs_inbound.yaml`

*** ** * ** ***

## Common Patterns {#common-patterns}

### Pull-Based Integration {#pull-based-integration}

1. Retrieve alerts: `GET /alerts` → receives batch of alerts
2. Acknowledge receipt: `POST /alerts/acknowledges` → confirm processing
3. Investigate each alert (asynchronously)
4. Submit outcomes: `POST /outcomes` → send investigation results

See [Pull Alert Processing Use Case](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/use-cases/pull-alert-processing.md) for detailed flow and examples.

### Push-Based Integration {#push-based-integration}

1. Register webhook URL with Ethoca Customer Delivery Team
2. Receive alerts: Ethoca sends `POST` to your webhook URL
3. Respond immediately: Return HTTP 200 OK with acknowledgement
4. Investigate asynchronously
5. Submit outcomes: `POST /outcomes` → send investigation results

See [Push Alert Processing Use Case](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/use-cases/push-alert-processing.md) for detailed flow and examples.

*** ** * ** ***

## Authentication {#authentication}

All API calls require OAuth 1.0a authentication. Include the `Authorization` header with a cryptographic signature on every request.

**Required Credentials:**

* Consumer Key (OAuth identifier)
* `.p12` Keystore file (with private signing key)
* Keystore password and key alias

See [Authentication \& Encryption](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/api-basics/authentication-and-encryption.md) for detailed setup instructions.

*** ** * ** ***

## Rate Limits and Batch Sizes {#rate-limits-and-batch-sizes}

* **Alert Retrieval:** Maximum 1,000 alerts per `GET /alerts` request
* **Outcome Submission:** Maximum 25 outcomes per `POST /outcomes` request
* **Acknowledgement:** Maximum 1,000 acknowledgements per `POST /alerts/acknowledges` request

For large batches, split into multiple requests as needed.

*** ** * ** ***

## Response Format {#response-format}

All successful responses return HTTP 200 OK with a JSON body. Error responses include an `Errors` envelope with detailed reason codes.

**Success Response Example:**

```json
{
  "alerts": [
    {
      "alertId": "ALERT_ID_12345",
      "alertType": "CUSTOMERDISPUTE",
      "transactionAmount": "100.00",
      "transactionCurrency": "USD",
      "dateSubmitted": "2024-06-23",
      "customerName": "John Doe",
      "cardLastFour": "5678",
      "merchantName": "Example Merchant",
      "transactionRef": "TXN_REF_12345"
    }
  ]
}
```

**Error Response Example:**

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "API",
        "ReasonCode": "VALIDATION_FAILURE",
        "Description": "Invalid date format. Expected YYYY-MM-DD.",
        "Recoverable": false
      }
    ]
  }
}
```

See [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md) for comprehensive error code reference.

*** ** * ** ***

## Good to Know {#good-to-know}

* Review [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/quick-start-guide.md) for integration setup
* Explore [Use Cases](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/use-cases/index.md) for detailed endpoint flows
* Check [Support](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md) for common questions and troubleshooting
* Visit [Developer Tools](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/index.md) for Postman, Insomnia, and Reference Application

## Next Steps {#next-steps}

Now that you have a good understanding of all the services endpoints, proceed to the [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md) section to learn about test scenarios and validation workflows.