# Support
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md

## Ethoca Alerts for Merchants Support and Frequently Asked Questions {#ethoca-alerts-for-merchants-support-and-frequently-asked-questions}

This page addresses the most common questions developers encounter when integrating Ethoca Alerts for Merchants. If you don't find your answer below, scroll to [Getting Help](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md#getting-help) for support channels.

## General {#general}

### What is Ethoca Alerts for Merchants? {#what-is-ethoca-alerts-for-merchants}

Ethoca Alerts for Merchants is a real-time alert service that notifies you of potential fraud and dispute transactions before they become chargebacks, enabling faster resolution and reduced chargeback costs.

**Common causes for confusion:** Developers sometimes conflate it with chargeback management systems; this is specifically an *alert and response* platform.

**Solution:** Review the [Overview](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/index.md) page to understand the three integration surfaces: Push webhook delivery, Pull retrieval, and Outcome submission.

**More info:** [What Is Ethoca Alerts for Merchants?](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/what-is-ethoca-alerts-for-merchants/index.md)

*** ** * ** ***

### What are the three ways to integrate with Ethoca Alerts? {#what-are-the-three-ways-to-integrate-with-ethoca-alerts}

The three integration surfaces are:

* **Push** --- Ethoca sends alerts to your webhook endpoint in real-time

* **Pull** --- You retrieve alerts from Ethoca on a schedule

* **Outcome** --- You submit the result of your investigation back to Ethoca (used by both Push and Pull).

**Common causes for confusion:** Some developers think Push and Pull are mutually exclusive; in reality, they are orthogonal delivery and retrieval methods, both ending with Outcome submission.

**Solution:** Choose Push if you want real-time notifications, or Pull if you prefer polling. Your Ethoca Customer Delivery Team can enable either or both.

**More info:** [Use Cases](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/use-cases/index.md), [How It Works Diagrams](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/index.md#how-it-works)

*** ** * ** ***

### Which environments are available for testing and production? {#which-environments-are-available-for-testing-and-production}

* **Sandbox** (`https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants`) is for development and testing.
* **Production** (`https://api.ethocaweb.com/ethoca/alerts/merchants`) is for live data.

**Common causes for confusion:** Some developers forget to switch URLs when moving from Sandbox to Production.

**Solution:** Store environment URLs in configuration; verify the correct URL is being used in each environment.

**More info:** [API Basics](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/index.md#environments)

*** ** * ** ***

## Authentication {#authentication}

### How do I set up OAuth 1.0a authentication? {#how-do-i-set-up-oauth-10a-authentication}

OAuth 1.0a requires a consumer key and a `.p12` keystore file with your private signing key. Use these to generate an `Authorization` header with a cryptographic signature on every API request.

**Common causes for failure:** Incorrect keystore password, wrong key alias, or invalid signature generation algorithm.

**Solution:**

1. Download your consumer key and `.p12` keystore from Mastercard Developers
2. Use an OAuth 1.0a client library (for example, Mastercard java-sdk, Node.js oauth1a packages)
3. Test in Sandbox first
4. Verify the signature algorithm matches your keystore.

**More info:** [Authentication \& Encryption](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/authentication-and-encryption/index.md), [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/)

*** ** * ** ***

### Why am I getting a 401 Unauthorized error? {#why-am-i-getting-a-401-unauthorized-error}

A 401 error indicates your OAuth signature is invalid or your credentials are missing/incorrect.

**Common causes:**

* Incorrect consumer key or keystore password
* Signature algorithm mismatch
* Missing `Authorization` header
* Keystore file corrupted or key alias not found
* Request timestamp outside the acceptable window

**Solution:**

1. Verify consumer key and keystore in the Mastercard Developers portal.
2. Test signature generation with a known-good client library.
3. Confirm keystore password and key alias.
4. Check system time synchronization (request timestamps must be within \~5 minutes of server time).
5. Test in Sandbox first.

**More info:** [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md#authentication-and-authorization-errors)

*** ** * ** ***

### Do I need to rotate my API credentials? {#do-i-need-to-rotate-my-api-credentials}

Credential rotation policies depend on your organization's security requirements. Mastercard recommends rotating credentials periodically as a security best practice.

**Common causes for rotation need:** Suspected compromise, expired keys, or security policy compliance.

**Solution:** Contact your Mastercard account manager or the Developer Support portal to request credential rotation. Generate new `.p12` keystore and consumer key; test in Sandbox before deploying to Production.

**More info:** [Getting Help](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md#getting-help)

*** ** * ** ***

## Integration \& Testing {#integration--testing}

### How do I retrieve alerts using the Pull API? {#how-do-i-retrieve-alerts-using-the-pull-api}

Use `GET /alerts` with optional query parameters: `alert_type` (filter by `CUSTOMERDISPUTE` or `CONFIRMEDFRAUD`), `from_date` (YYYY-MM-DD), `to_date` (YYYY-MM-DD), and `size` (1--1000, default varies).

**Common causes for empty results:** No alerts available in the date range, or incorrect date format.

**Solution:** Start with a narrow filter like `alert_type=CUSTOMERDISPUTE&size=1` to confirm connectivity; expand the date range or remove filters to search for more alerts.

**More info:** [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/quick-start-guide.md#test-the-sandbox), [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md#positive-testing)

*** ** * ** ***

### What is the maximum batch size for outcomes? {#what-is-the-maximum-batch-size-for-outcomes}

You can submit a maximum of **25 outcomes** in a single `POST /outcomes` request.

**Common causes for batch-too-large error:** Submitting more than 25 outcomes at once.

**Solution:** Split large outcome batches into chunks of 25 or fewer; submit in separate requests.

**More info:** [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md#validation-errors)

*** ** * ** ***

### What do I do if I receive duplicate alerts? {#what-do-i-do-if-i-receive-duplicate-alerts}

Duplicate alerts can occur during webhook retransmission. Deduplicate based on `alertId` and handle idempotently --- acknowledge or submit the same outcome for the same alert ID should return success without error.

**Common causes:** Webhook retry mechanisms, network issues causing missed acknowledgements.

**Solution:** Implement idempotent alert handling; store processed `alertId` values; if you receive the same alert twice, return `SUCCESS` for both acknowledgements.

**More info:** [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md#negative-testing)

*** ** * ** ***

### How long can I take to respond to an alert? {#how-long-can-i-take-to-respond-to-an-alert}

Best practice is to respond with a final outcome within **24 hours** of receiving the alert to maximize the chance of stopping the chargeback.

**Common causes for late response:** Slow investigation workflow, alerts stuck in queues.

**Solution:** Implement alerts/monitoring for alerts older than 20 hours; prioritize investigation workflows; use outcome status `IN_PROGRESS` or `SHIPPER_CONTACTED` to indicate ongoing investigation (though these are non-final and should be followed by a final outcome within 24 hours).

**More info:** [Overview](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/index.md#how-it-works)

*** ** * ** ***

### How do I test negative scenarios in Sandbox? {#how-do-i-test-negative-scenarios-in-sandbox}

Use invalid request data to trigger errors: invalid date formats, duplicate acknowledgements, missing mandatory fields, or invalid enum values.

**Common causes for missing test coverage:** Not systematically testing error paths.

**Solution:** Follow the negative test cases in the [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md#negative-testing) page; test each error code at least once; verify `Recoverable` flag handling in your code.

**More info:** [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md#negative-testing)

*** ** * ** ***

## Push Webhook Integration {#push-webhook-integration}

### How do I register my webhook endpoint for Push alerts? {#how-do-i-register-my-webhook-endpoint-for-push-alerts}

Your Ethoca Customer Delivery Team registers your webhook endpoint during onboarding. Provide a HTTPS URL (for example, `https://yourdomain.com/ethoca/alerts`).

**Common causes for registration issues:** Non-HTTPS URL, network firewall blocking Ethoca IPs, or endpoint returning non-200 status codes.

**Solution:**

1. Confirm your webhook URL is publicly accessible and HTTPS-only.
2. Ensure your endpoint returns HTTP 200 OK with acknowledgement status in response body (see spec).
3. Test with curl or Postman before providing URL to Customer Delivery Team.

**More info:** [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/quick-start-guide.md#step-6-service-specific-onboarding), [Use Cases -- Push Alert Processing](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/use-cases/push-alert-processing.md)

*** ** * ** ***

### Why is Ethoca not pushing alerts to my webhook? {#why-is-ethoca-not-pushing-alerts-to-my-webhook}

Your endpoint may not be reachable, returning non-200 status, not responding within the timeout window, or not signed correctly if signature validation is enabled.

**Common causes:**

* Webhook URL has typo or is not publicly accessible
* Endpoint returns error status (4xx or 5xx) instead of 200
* Endpoint response takes too long
* Network firewall or security group blocking Ethoca IPs
* DigiCert certificate validation failing

**Solution:**

1. Verify webhook URL is correct and publicly reachable (test with curl).
2. Confirm endpoint returns 200 OK.
3. Check server logs for incoming requests.
4. If no requests arrive, contact Ethoca Customer Delivery Team to confirm registration and IP allowlisting.

**More info:** [API Basics -- DigiCert Root Certificates](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/api-basics/digicert-root-certificates.md), [Support -- Getting Help](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md#getting-help)

*** ** * ** ***

### How do I validate Ethoca webhook signatures? {#how-do-i-validate-ethoca-webhook-signatures}

If signature validation is enabled, Ethoca includes a digital signature header in webhook requests. Validate the signature using Ethoca's public certificate (DigiCert root).

**Common causes for validation failures:** Missing certificate, incorrect algorithm, or certificate expired.

**Solution:**

1. Download DigiCert root certificates from the [DigiCert Root Certificates](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/api-basics/digicert-root-certificates.md) page.
2. Import into your trust store.
3. Validate incoming webhook signatures using standard TLS validation.
4. Test in Sandbox first.

**More info:** [API Basics -- DigiCert Root Certificates](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/api-basics/digicert-root-certificates.md)

*** ** * ** ***

## Onboarding \& Production {#onboarding--production}

### What happens after I complete Sandbox testing? {#what-happens-after-i-complete-sandbox-testing}

After testing, request Production access from your Ethoca Customer Delivery Team. They will review your integration, conduct a final validation in MTF (Merchant Test Facility) if required, and enable Production credentials.

**Common causes for delays:** Incomplete Sandbox testing, missing required documentation, or compliance/KYC process.

**Solution:** Ensure your integration passes all positive and negative test scenarios; provide a summary of test results; confirm business details and technical contact information with Customer Delivery Team.

**More info:** [Onboarding Checklist](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/onboarding-checklist.md)

*** ** * ** ***

### How long does production enablement take? {#how-long-does-production-enablement-take}

Production enablement typically takes **2--5 business days** after your request, pending validation and compliance checks.

**Common causes for delays:** Incomplete onboarding information, additional security reviews, or high request volume.

**Solution:** Provide complete onboarding information upfront; allow 1--2 extra days as a buffer; check with your Mastercard account manager for current SLA.

**More info:** [Onboarding Checklist](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/onboarding-checklist.md)

*** ** * ** ***

### What credentials do I need for Production? {#what-credentials-do-i-need-for-production}

You will receive a Production OAuth 1.0a consumer key and `.p12` keystore file. These are distinct from your Sandbox credentials and should be treated as sensitive (store securely, rotate annually).

**Common causes for confusion:** Using Sandbox credentials in Production, or vice versa.

**Solution:**

1. Store Production and Sandbox credentials in separate configuration files.
2. Never commit credentials to source control.
3. Use environment variables or a secrets manager.
4. Test Production credentials in a staging environment before going live.

**More info:** [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/quick-start-guide.md#step-7-promote-to-production), [API Basics](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/index.md#environments)

*** ** * ** ***

## Outcomes \& Results {#outcomes--results}

### What outcome codes should I submit? {#what-outcome-codes-should-i-submit}

For **Confirmed Fraud** alerts, use: `STOPPED`, `PARTIALLY_STOPPED`, `PREVIOUSLY_CANCELLED`, `MISSED`, `NOT_FOUND`, `ACCOUNT_SUSPENDED`, or `OTHER`.

For **Customer Dispute** alerts, use: `RESOLVED`, `RESOLVED_PREVIOUSLY_REFUNDED`, `UNRESOLVED_DISPUTE`, `NOT_FOUND`, or `OTHER`.

**Common causes for invalid outcomes:** Submitting fraud outcomes for dispute alerts, or vice versa.

**Solution:** Check the alert's `alertType` field; match your outcome to the alert type; use `OTHER` with detailed comments if your specific outcome doesn't fit the standard codes.

**More info:** [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md#outcome-codes)

*** ** * ** ***

### Can I update an outcome after submission? {#can-i-update-an-outcome-after-submission}

The API does not support outcome updates; the first final-state outcome you submit is the one sent to the issuer. If you need to correct an outcome, contact your Ethoca Customer Delivery Team for manual intervention.

**Common causes for update needs:** Incomplete investigation, data entry error, or manual review discovering new information.

**Solution:** Validate outcome data before submission; include detailed comments with investigation findings; if you must update, contact support immediately with alert IDs and corrected outcome information.

**More info:** [Support -- Getting Help](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md#getting-help)

*** ** * ** ***

## Errors \& Troubleshooting {#errors--troubleshooting}

### How do I interpret error responses? {#how-do-i-interpret-error-responses}

All errors are returned in an `Errors` envelope with a `ReasonCode` (for example, `VALIDATION_FAILURE`), `Description`, and `Recoverable` flag. Check the flag to decide whether to retry.

**Common causes for misinterpretation:** Treating all errors as permanent, or all errors as retryable.

**Solution:** Always check the `Recoverable` flag; if `true`, implement exponential backoff retry; if `false`, fix the underlying issue before resubmitting.

**More info:** [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md#error-response-structure)

*** ** * ** ***

### What should I do if I see a 400 Bad Request error? {#what-should-i-do-if-i-see-a-400-bad-request-error}

A 400 error indicates your request is malformed or fails validation (for example, invalid date format, missing mandatory field, duplicate acknowledgements).

**Common causes:**

* Date format not YYYY-MM-DD for query parameters
* Missing required outcome fields
* Duplicate alert IDs in a single batch
* Invalid enum value for outcome or refund status

**Solution:**

1. Check the error `Details` field for the specific issue.
2. Review the request against the OpenAPI spec.
3. Fix the malformed field.
4. Resubmit.

**More info:** [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md#http-status-to-reason-code-mapping), [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md#negative-testing)

*** ** * ** ***

### My acknowledgement request failed with "Acknowledge should be Unique" --- what does this mean? {#my-acknowledgement-request-failed-with-acknowledge-should-be-unique--what-does-this-mean}

You sent the same alert ID more than once in the same `POST /alerts/acknowledges` request.

**Common causes:** Duplicate logic in batch construction or accidental array duplicates.

**Solution:** Deduplicate alert IDs before sending; ensure each alertId appears only once per request.

**More info:** [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md#validation-errors)

*** ** * ** ***

## Developer Tools {#developer-tools}

### Is there a reference application I can use to learn? {#is-there-a-reference-application-i-can-use-to-learn}

Yes. The [Reference Application](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/reference-app.md) demonstrates a complete end-to-end integration with Pull alert retrieval, acknowledgement, and outcome submission.

**Common causes for not using it:** Unaware of the reference app, or assuming it's for a different language/framework.

**Solution:** Review the [Reference Application](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/reference-app.md) tutorial and source code; adapt patterns for your tech stack.

**More info:** [Developer Tools](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/index.md)

*** ** * ** ***

### Can I use Postman or Insomnia to test the API? {#can-i-use-postman-or-insomnia-to-test-the-api}

Yes. Pre-built collections are available for both [Postman](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/postman-collection.md) and [Insomnia](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/insomnia-collection.md) that include all endpoints with OAuth configuration examples.

**Common causes for skipping tool usage:** Not knowing collections exist, or preferring custom scripts.

**Solution:** Import the relevant collection for your preferred tool; follow the setup instructions to configure environment variables and OAuth; run requests directly from the collection.

**More info:** [Postman Collection](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/postman-collection.md), [Insomnia Collection](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/insomnia-collection.md)

*** ** * ** ***

## Getting Help {#getting-help}

### How do I get support if my issue is not listed above? {#how-do-i-get-support-if-my-issue-is-not-listed-above}

**Support Channel:**

* **Primary:** [Mastercard Developer Support Portal](https://developer.mastercard.com/support) --- For API issues, authentication, sandbox testing, and general integration questions.
* **Secondary:** Your Ethoca Customer Delivery Team --- For onboarding, production enablement, webhook configuration, and business-specific issues.

**Expected Response Time:**

* Standard support: 24--48 business hours
* Urgent (production outage): 2--4 hours

### What information should I include in a support request? {#what-information-should-i-include-in-a-support-request}

Include the following to expedite resolution:

1. **API Environment:** Sandbox or Production
2. **Endpoint:** Which endpoint are you calling (for example, `GET /alerts` or `POST /outcomes`)
3. **Error Message \& Code:** Full error response with HTTP status and reason code
4. **Request Details:** Sanitized request payload (remove sensitive credentials)
5. **Timestamp:** Exact time the error occurred (timezone)
6. **Frequency:** Does the error occur every time or intermittently?
7. **Steps to Reproduce:** Clear steps to trigger the issue

**For webhook issues:**

* Webhook URL and expected response format
* Recent webhook logs from your server
* Any error messages in your application logs

*** ** * ** ***

### Where can I find API documentation and specifications? {#where-can-i-find-api-documentation-and-specifications}

All documentation is on this site:

* [Overview](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/index.md) --- Service description and value proposition
* [API Basics](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/index.md) --- Authentication, encryption, environments
* [Quick Start Guide](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/quick-start-guide/index.md) --- Integration walkthrough
* [Use Cases](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/use-cases/index.md) --- Real-world integration patterns
* [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md) --- Sandbox test cases and validation workflows
* [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md) --- Error codes and response formats
* [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-reference/index.md) --- Interactive endpoint documentation
* [Tutorials and Guides](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/index.md) --- Endpoint-specific walkthroughs

OpenAPI specification files are available for download at [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-reference/index.md).

*** ** * ** ***

### How do I report a security vulnerability? {#how-do-i-report-a-security-vulnerability}

Do **not** report security vulnerabilities publicly on this site or in the portal. Contact Mastercard Security immediately:

* **Email:** [security@mastercard.com](mailto:security@mastercard.com)
* Include: Vulnerability description, affected endpoint, proof of concept, and recommended fix

*** ** * ** ***

## Get Help {#get-help}

### Contact us for technical support. {#contact-us-for-technical-support}

Get Help