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

## Ethoca Alerts for Merchants API Basics and Environments {#ethoca-alerts-for-merchants-api-basics-and-environments}

This section covers the integration fundamentals for Ethoca Alerts for Merchants, including authentication, available specifications, and the environments you use during implementation. The API surface spans three related flows:

* Push delivery to your webhook

* Pull retrieval and acknowledgement

* Outcome submission back to Ethoca

## Authentication {#authentication}

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

* Use your project consumer key and signing key to generate the OAuth 1.0a `Authorization` header for requests to `GET /alerts`, `POST /alerts/acknowledges`, and `POST /outcomes`.
* For implementation guidance, 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/).
* If you generate a client from the OpenAPI specifications, you can also follow [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/).

For Push integrations, Mastercard sends alerts to the HTTPS endpoint that you expose. That delivery model doesn't change the authentication method for the Mastercard-hosted APIs, but your webhook infrastructure might need to trust the Mastercard client certificate chain used for outbound delivery. See [Authentication and Encryption](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/authentication-and-encryption/index.md) and [DigiCert Root Certificates](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/digicert-root-certificates/index.md).

## How to Consume the API {#how-to-consume-the-api}

You can integrate with the service in two common ways:

* Generate an API client from the OpenAPI specifications and use Mastercard libraries to handle OAuth signing.
* Use your own HTTP client and sign requests yourself with OAuth 1.0a.

Download the specifications that apply to your integration pattern:

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

If you are building a Pull or Outcome client, the generated-client approach is usually the fastest way to get a working integration. If you are implementing Push, use the outbound specification to validate the webhook payload your endpoint must accept.

## Environments {#environments}

The Mastercard-hosted APIs provide Sandbox and Production environments.

| Integration surface |                           Sandbox                           |                     Production                      |
|---------------------|-------------------------------------------------------------|-----------------------------------------------------|
| Pull API            | `https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants` | `https://api.ethocaweb.com/ethoca/alerts/merchants` |
| Outcome API         | `https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants` | `https://api.ethocaweb.com/ethoca/alerts/merchants` |
| Push API            | Your Sandbox HTTPS webhook endpoint                         | Your Production HTTPS webhook endpoint              |

Sandbox supports integration testing with mock responses and sample test scenarios documented in [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md). For Push, the sample specification uses placeholder hosts because Mastercard posts alerts to the endpoint that you register during onboarding.

## Additional Integration Notes {#additional-integration-notes}

* Pull integrations retrieve unacknowledged alerts with `GET /alerts` and confirm receipt with `POST /alerts/acknowledges`.
* Outcome submissions support batches of up to 25 alerts per request.
* Pull retrieval can return up to 1000 alerts in a request, based on the API specification.
* The service supports both confirmed fraud and customer dispute alert types.

## Next Steps {#next-steps}

Now that you have an understanding of the service authentication and encryption model, proceed to the [Use Cases](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/use-cases/index.md) section to see how to receive dispute and fraud alerts through the Push and Pull APIs, acknowledge them, and send results through the Outcome API.