# 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.