# Support
source: https://developer.mastercard.com/merchant-self-services/documentation/support/index.md

Use this page to find answers to common Merchant Self Services questions and identify the next documentation or support resource for your needs. Detailed setup, testing, troubleshooting, and production procedures remain on their dedicated pages.

## What should I do next? {#what-should-i-do-next}

#### I am new to Merchant Self Services {#i-am-new-to-merchant-self-services}

1. Start with the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md) to create a project, obtain Sandbox credentials, configure authentication, and make your first Sandbox API call.
2. Continue to the [Reference Application Tutorial](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/reference-app-tutorial/index.md) for a complete Java integration example.
3. Use the [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) section to validate your integration against the applicable Consumer Clarity or Ethoca Alerts for Merchants test cases.
4. Refer to the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md) for endpoint requirements, request fields, response schemas, and successful status codes.

#### I want to test my integration {#i-want-to-test-my-integration}

1. Confirm that you completed the setup and first Sandbox call in the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md).
2. Choose your testing method from the [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) page.
3. Run the applicable [Clarity Test Cases](https://developer.mastercard.com/merchant-self-services/documentation/testing/clarity-test-cases/index.md) or [Alerts Test Cases](https://developer.mastercard.com/merchant-self-services/documentation/testing/alerts-test-cases/index.md).
4. Use the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md) to validate required inputs, response status codes, schemas, identifiers, and response headers.

#### I am receiving an API error {#i-am-receiving-an-api-error}

1. Record the HTTP status code and review every object in the `Errors.Error` array.
2. Use [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) to identify the API-specific reason code and recovery guidance.
3. Compare the request with the operation definition in the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md).
4. For authentication, authorization, request-signing, throttling, or other gateway-layer errors, follow the official gateway-error reference at [OAuth 1.0a and mTLS Error Codes](https://developer.mastercard.com/platform/documentation/errors-and-troubleshooting/oauth1-and-mtls-error-codes/).
5. If the issue remains unresolved, contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com).

#### I am preparing for Production access {#i-am-preparing-for-production-access}

1. Complete your Sandbox integration and the applicable validation workflow in [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md).
2. Review the production-access guidance in the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md#move-to-production).
3. Request Production access for your Mastercard Developers project.
4. Work with the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com) to complete the required onboarding activities.

## FAQ {#faq}

### General {#general}

[Ethoca](https://www.ethoca.com/) is an award-winning provider of collaboration-based intelligence and technology solutions that empower businesses around the world to fight fraud, prevent disputes, and improve the customer experience.

Powered by the ever-growing Ethoca Network, our solutions provide rich intelligence throughout the customer purchase journey and close costly communication gaps between all stakeholders in the payments ecosystem. These include thousands of the world's biggest ecommerce brands, the largest banks, service providers, and consumers. For the first time, fraud, customer dispute, and purchase insights are now available and actionable in real time, delivering significant revenue growth and cost-saving opportunities for all.

Ethoca was acquired by Mastercard in April 2019.
No. All merchants must integrate with the Merchant Transaction API. The Merchant Self Services API lets a merchant with multiple sub-merchants or sub-brands enter them during the integration process.

For Merchant Self Services setup, start with the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md). For information about Merchant Transaction API onboarding, contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com).
Contact [Ethoca Sales](mailto:sales@ethoca.com) for pricing information.

### Onboarding {#onboarding}

Use this documentation path:

1. Complete the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md) for project setup, Sandbox credentials, authentication, and a first API call.
2. Follow the [Reference Application Tutorial](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/reference-app-tutorial/index.md) for a complete Java example.
3. Use [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) to validate the applicable Consumer Clarity or Ethoca Alerts for Merchants workflow.
4. Refer to the [API Reference](https://developer.mastercard.com/merchant-self-services/documentation/api-reference/index.md) while implementing individual operations.
5. Use [Code and Formats](https://developer.mastercard.com/merchant-self-services/documentation/code-and-formats/index.md) when troubleshooting API-specific reason codes.
On average, onboarding takes between 8 weeks and 4 months.

**Common causes of a longer timeline:**

* Limited availability of your development team.
* Delays in getting access to required resources, such as your Sandbox environment.
* Integrating the Merchant Transaction API or the Alerts for Merchants APIs at the same time.

**To keep onboarding on track:**

1. Complete the [Quick Start Guide](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md) to get Sandbox access and make your first call.
2. Run the [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) workflow for your product.
3. Follow the [Move to Production](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md#move-to-production) workflow.
4. Contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com) for questions specific to your implementation.
Register each submerchant with its own requests. There is no single bulk-upload operation, but you can script the same sequence for every submerchant.

**Steps:**

1. For Ethoca Alerts, follow [Register Submerchants and Descriptors for Ethoca Alerts](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/register-alerts-submerchants/index.md).
2. For Consumer Clarity, follow [Onboard a submerchant](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#onboard-a-submerchant).
3. To keep brand details current after onboarding, follow [Maintain Brand Information for Consumer Clarity](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/maintain-consumer-clarity-brand-information/index.md).
Production access requires a working Sandbox integration, Mastercard approval, and assistance from the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com). Approval typically takes two to five days.

**Common causes of delay:**

* The Sandbox validation workflow is incomplete.
* The production request form is missing contact details.

**Steps:**

1. Complete the applicable validation workflow in [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md).
2. Follow the ordered stages in [Move to Production](https://developer.mastercard.com/merchant-self-services/documentation/tutorials-and-guides/quick-start-guide/index.md#move-to-production).
3. If approval exceeds the stated timeframe, use the escalation path on the same page.

### Data and Matching {#data-and-matching}

Other than the fields outlined in your agreement, Ethoca doesn't store transaction data that a merchant provides in response to a request. In addition, Ethoca never stores merchant customer information that is considered **Personally Identifiable Information (PII)**.

For questions about the data requirements in your agreement, contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com).
The API rejects a card acceptor name or an Acquirer Reference ID - Card Acceptor ID pair when it is already associated with another merchant. The rest of the request can still succeed.

**Common causes:**

* The name or pair is registered to a different merchant or submerchant.
* The card acceptor name is too generic and collides with another merchant's name.

**Steps:**

1. Check the response. Rejected card acceptor names have a status of `FAILED`. Rejected pairs appear in `rejectedIds`.
2. Confirm which of your merchants should own the value.
3. Resend a more specific card acceptor name, or remove the pair from the other merchant first.
4. See [Add card acceptor names with at least one valid name](https://developer.mastercard.com/merchant-self-services/documentation/use-cases/clarity-use-cases/index.md#add-card-acceptor-names-to-an-existing-submerchant-default-location-with-at-least-one-valid-card-acceptor-name) for an example.
Ethoca shows your details only when the transaction descriptor matches a card acceptor name you registered.

**Common causes:**

* The registered card acceptor name does not match the start of the descriptor on the cardholder statement.
* The descriptor varies by channel or acquirer, and only one variation is registered.

**Steps:**

1. Compare the descriptors on real statements with your card acceptor names using **getCardAcceptorNames**.
2. Add a card acceptor name for each descriptor variation.
3. Review [Matching Logic Recommendations](https://developer.mastercard.com/merchant-self-services/documentation/api-basics/index.md#matching-logic-recommendations) to choose between `<STARTS-WITH>` and `<EXACT>` matching.
4. Contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com) if `<STARTS-WITH>` and `<EXACT>` still undermatch.

### Performance {#performance}

These are the key performance requirements every merchant is expected to meet:

* **Response time:** Sub-second response time is ideal, but no more than 2 seconds per request.
* **Average load:** Single request at a time.
* **Peak load:** 200 transactions per second.

Use the [Testing](https://developer.mastercard.com/merchant-self-services/documentation/testing/index.md) section to validate your integration workflow. Contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com) for questions about how these requirements apply to your implementation.

## Get Help {#get-help}

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

Get Help