# Onboarding FAQ
source: https://developer.mastercard.com/consumer-clarity/documentation/support/onboarding-faq/index.md

* [General](https://developer.mastercard.com/consumer-clarity/documentation/support/onboarding-faq/index.md#general)
* [Coverage](https://developer.mastercard.com/consumer-clarity/documentation/support/onboarding-faq/index.md#coverage)
* [Response data](https://developer.mastercard.com/consumer-clarity/documentation/support/onboarding-faq/index.md#response-data)

### 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.
The following information is supported:

* Recognizable merchant name
* Logo
* Geolocation
* Merchant category code and description
* Purchase information (digital receipt URL) is available for some merchants   

In markets where we have more accurate location information, these fields are also available:

* Merchant address
* Description of products and services
* Website
The `type` field value provides insight into how close in proximity the latitude and longitude information that's returned for `merchantLocation` is to the actual Merchant location.

See [Understanding the geolocation proximity from the response](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/displaying-merchant-details/index.md#understanding-the-geolocation-proximity-from-the-response) for more details about the specific response data returned by the `type` field.
Yes. Card acceptor (or merchant) data from pending and settled transaction submissions are used for matching to our extensive merchant data set. This is not limited to Mastercard-processed transactions. No. Both pending and settled transactions are supported. Since direct debit transactions are processed from bank account to bank account, they don't flow through the same card scheme that a credit card transaction does. As a result, direct debit transactions are not currently supported by Consumer Clarity. Currently, Consumer Clarity merchant results data supports only English.

The data in the Consumer Clarity Digital Receipts service supports multiple languages. The locale (language-country combination) is associated with the location from which you make your request. You can include a specific locale in your request, which determines the language displayed on the receipt.

The languages that are currently supported for receipts are:

|  Locale   |       Description        |
|-----------|--------------------------|
| **en-CA** | (Canadian English)       |
| **en-GB** | (United Kingdom English) |
| **en-US** | (American English)       |
| **es-ES** | (Castilian Spanish)      |
| **es-MX** | (Mexican Spanish)        |
| **es-US** | (Spanish-United States)  |
| **fr-CA** | (Canadian French)        |
| **fr-FR** | (French-France)          |
| **pt-BR** | (Brazilian Portuguese)   |
| **pt-PT** | (European Portuguese)    |

See the [Quick Start Guide](https://developer.mastercard.com/consumer-clarity/documentation/quick-start-guide/index.md) for steps on setting up your project and accessing the sandbox. After you successfully integrate in sandbox (see the [Reference Application Tutorial](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/reference-app-tutorial/index.md)), you can convert your sandbox keys to production. Request Production access for your project, which requires approval from Mastercard and assistance from the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com). Contact [sales@ethoca.com](mailto:sales@ethoca.com) for pricing information.

### Coverage {#coverage}

The availability of specific merchant attributes may differ from country to country. Availability is based on the completeness and quality of information as well as any applicable country data privacy laws.

Contact your Mastercard or [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com) representative for more information about market specifics.

### Response data {#response-data}

The API searches on the merchant details provided in the request. Card Brand, Card Type and the Pending/Settled state don't affect the Consumer Clarity part of the response. For a bulk request to `POST /consumer-clarity/searches`, the response entries are returned in the same order as the search criteria in the request.

1. Preserve the order of items in the `searchCriteria` array.
2. Match each response entry to the request entry in the same position.
3. Retain the returned [`recordId`](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#troubleshooting-bulk-requests) if you need to investigate an individual result.
Merchant data, including a recognizable merchant name, contact information, address or location, and logo, is available for authorization and settled transactions, assuming the authorization descriptor includes this information.

Receipt availability depends on the merchant integration and how they perform transaction matching. For example, if they only provide an ARN, then a receipt is only available for settled transactions.
No, the API doesn't return multiple merchants. Instead, we return the most frequent merchant match based on transaction volume when multiple merchant locations are returned for one descriptor. Where no single merchant is found, the API returns `Merchant Not Found` in the response. Consumer Clarity is capable of displaying the actual merchant name instead of the provider. In practice, for some merchants we will return the merchant name while some will have the provider name because of the differences in how the provider handles their transactions. This is true even within the same provider, depending on their arrangements with different merchants. The receipt is a URL. These articles provide more information about digital receipts:

* [How to Use the Response Data](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/index.md#provide-a-purchase-receipt) gives advice about handling the receipt URL in your banking app.
* The [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis) provides more detail about receipts under the **Defined Response** \> **Model** tab.
No, the logos are only intended by merchants to be used within the digital banking experience and can't be used for any other purpose. Reach out to your Account Manager or contact [Ethoca Sales](mailto:sales@ethoca.com) to complete an enrollment form.

### Troubleshooting {#troubleshooting}

#### Explanation {#explanation}

Consumer Clarity cannot process an API request unless it contains a valid access token in the `Authorization` header.

This issue can affect Consumer Clarity endpoints such as `POST /consumer-clarity/searches` and `POST /consumer-clarity/backoffice-searches`.

#### Common causes {#common-causes}

* The access token is missing or no longer valid.
* The `Authorization` header is missing.
* The header does not use the required `Bearer <access_token>` format, including the space after `Bearer`.
* Sandbox credentials are being used for a production request, or production credentials are being used for a sandbox request.

#### Steps to resolve {#steps-to-resolve}

1. Generate an access token using the credentials for the environment you are calling.
2. Add the token to the request header in this format:

```http
Authorization: Bearer <access_token>
```

3. Confirm that there is one space between `Bearer` and the access token.
4. Confirm that the credentials and Consumer Clarity endpoint belong to the same environment.
5. Send the request again with the corrected header.

See the authentication guidance in the [Quick Start Guide](https://developer.mastercard.com/consumer-clarity/documentation/quick-start-guide/index.md) and the endpoint definitions in the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis).

#### Explanation {#explanation}

Consumer Clarity searches the merchant details supplied in the request. If no single merchant is found, the API returns `Merchant Not Found`.

#### Common causes {#common-causes}

* The merchant details in the request do not provide a sufficient match.
* The transaction involves a direct debit merchant, which Consumer Clarity does not support.
* The requested merchant attributes are not available for the applicable market or merchant.

#### Steps to resolve {#steps-to-resolve}

1. Review the `resultStatus` and message returned for the affected search result.
2. Compare the merchant and transaction criteria in the request with the source transaction data.
3. Correct any missing, malformed, or inaccurate criteria.
4. Compare the request with the `POST /consumer-clarity/searches` schema in the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis).
5. Send the corrected request.
6. If the response remains unexpected, save the request, response, and returned `recordId`, then contact the [Ethoca Customer Delivery Team](mailto:customerdelivery@ethoca.com).

## Get Help {#get-help}

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

Get Help