# Getting Started
source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md

Full integration with Ethoca's Merchant Transaction API proceeds in four phases:

* [Discovery](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md#discovery-phase)
* [Integration](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md#integration-phase)
* [Testing/Verification](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md#testing-and-verification-phase)
* [Deployment](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md#deployment-phase)   

Your Ethoca sales representative and Ethoca integration contact are available to assist at any point in the process. For integration support, please contact [customerdelivery@ethoca.com](mailto:customerdelivery@ethoca.com).
Note: Ethoca's Development team releases updates to the API on a frequent basis.  

If you receive documentation but are unable to complete development in a timely manner, check back with your Ethoca integration contact to make sure a newer version of the documentation has not been made available. They will make every attempt to provide the updated documentation once it becomes available.  

For more information about upcoming updates and recent ones, see the [Announcements](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/announcements/index.md) and [Release History](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/release-history/index.md) sections.

The process map below provides you with a clear, end-to-end view of the full integration journey, outlining each key phase to support a smooth onboarding experience:

![Integration Process Map](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/documentation/img/Clarity-Merchant-Integration-Process-Flow-SVG-v3.svg)

## Discovery Phase {#discovery-phase}

Through the sales process, a dedicated Ethoca integration contact will be assigned to you. They will be your reliable point of contact throughout the project, helping ensure a seamless onboarding experience through expert guidance and timely support when needed.

### Kickoff meeting {#kickoff-meeting}

In the Discovery phase, your Ethoca integration contact will provide you with the onboarding questionnaire and schedule a kickoff meeting with your technical team, business owners, and any other key stakeholders you'd like to include.

This kickoff meeting is an opportunity to:

* Discuss product functionality and technical specifications
* Define business cases
* Align on project goals and timelines
* Agree on project scope and launch prerequisites
* Review the integration process
* Answer any questions you may have

<br />

To get the most out of this initial meeting, review the following documentation prior to it:

* [Consumer Clarity for Merchants documentation](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/index.md)
* Merchant Transaction API Specification
  * **View:** [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#apis)
  * **Download:** [merchant_spec_4_0_0.yml](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/swagger/merchant_spec_4_0_0.yml) (131KB)
* Clarity: Merchant Onboarding and Integration Questionnaire

<br />

To begin the Integration phase after the kickoff meeting, complete the questionnaire and send it to your Ethoca integration contact (if you haven't done so already).

## Integration Phase {#integration-phase}

### Environment setup {#environment-setup}

Warning: Responses to API requests may include personally identifiable information (PII). Ethoca classifies this data as "Regulated-Classified". Consistent with Ethoca's policy on Applications and Systems Development and Maintenance, Ethoca requires that customers not deliver production data to the sandbox environment at any time.

You will need to create the following endpoints for both sandbox and production:

* **Transactions endpoint:** POST /api/orders
* **HealthChecks endpoint:** GET /api/orders/healthchecks
* **Merchant Actions endpoint:** PUT /subscriptions/actions/{action_id}
  * *Note: The Merchant Actions endpoint is only required for Smart Subscriptions.*
* **Merchant Notifications endpoint:** POST /merchants/notifications
  * *Note: The Merchant Notifications endpoint is only required to validate if a descriptor has been successfully onboarded.*
* **Merchant Reports endpoint:** POST /merchants/reports
  * *Note: The Merchant Reports endpoint is only required for First-Party Trust.*

<br />

While only the sandbox endpoints are required at this point, it is recommended to provide your production endpoints now if possible. This will minimize the time needed for production launch later in the process.

For more information, please see the [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md) section.

### API secret key generation {#api-secret-key-generation}

Your Ethoca integration contact will create an account for you in the system, and provision you with a sandbox API secret key, the key ID, and key version.

Once the endpoint allowlisting request is also complete, we will validate basic connectivity between the sandbox environments to begin testing.

### API development {#api-development}

As part of the API development, your technical team must complete the following tasks, working with your Ethoca integration contact for testing:

* **Define Available API Fields:** Identify required fields, business fields, and First-Party Trust fields (if applicable) available across all of the markets you do business in.
  * See the [Guide to API Fields for the Merchant Transaction API](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/api-fields-guide/index.md) section, the [Guide to Smart Subscriptions for Merchants](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/subscription-control-guide/index.md), and the [Data Dictionary](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#merchant-transaction-api-data-dictionary) for more details about fields.
* **Establish Transaction Matching Strategy:** Build fuzzy transaction matching logic that takes into account all of your acquirers.
  * See the [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md) and [Transaction Matching Guidance](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/transaction-matching-guidance/index.md) sections for more information.
* **Ensure Scalable Performance and Data Availability:** Set up a database architecture that allows for response time SLA (\< 2500ms) to be met and ensures that 13 months of transaction data will always be available within 24 hours of authorization.
* **Set Up API Server:** Implement a web server that serves the required API methods as described in [API Request/Response Common Elements and Headers](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/common-elements-headers/index.md).
* **Implement the HMAC Signature For Authentication:** [Create an HMAC signature](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/how-to-create-hmac-signature/index.md) header to provide with every request (along with the API key ID) and validate API authentication.
* **Develop API Workflows:** Build logic to receive requests, match transactions using fuzzy logic, and respond to requests.
  * See [Creating the JSON Response Message](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md#creating-the-json-response-message) below, and the [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md) and [Transaction Matching Guidance](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/transaction-matching-guidance/index.md) sections, for more information.
* **Implement Response Status Codes:** As outlined in the [Code and Formats](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/code-and-formats/index.md) section.

<br />

Your Ethoca integration contact can provide Postman or Insomnia API samples by request, to assist with your development process.

#### Creating the JSON response message {#creating-the-json-response-message}

This is the step that requires the most amount of development work. Alongside your Business Owner, you need to [identify which fields to include in your response](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/api-fields-guide/index.md), making sure to include the required fields that have been identified by Ethoca. Your Ethoca integration contact will provide recommendations on which fields to include using the Merchant Transaction API [Data Dictionary](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#merchant-transaction-api-data-dictionary).

Within your environment, you will need access to 13 months of transactional data always available within 24 hours of authorization, and able to respond in less than 2500ms. We will also collect information about your organization if we haven't already received it.

If you are participating in the First-Party Trust program, there are [certain fields that are used for compelling evidence](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/common-elements-headers/index.md#response-field-requirements). If these fields aren't included in your response, you can't shift the liability for the transaction in question. Work with your Ethoca integration contact to ensure these fields are part of your response.

#### Sandbox validations {#sandbox-validations}

Before proceeding to the Testing/Verification phase, the production endpoints must be allowlisted and the following tests must be successfully validated in sandbox:

* Connectivity
* Authentication with HMAC signature
* Correct format of request/response payloads
* Correct response status codes

## Testing and Verification Phase {#testing-and-verification-phase}

### Testing {#testing}

You must conduct thorough integration testing to ensure the foundational API functionality is in place before your integration can go live. Your Ethoca integration contact is available during this stage to support the testing process.

In the final step before being promoted to production on the Ethoca side, we validate connectivity, response latency, match rate, matching logic, and data quality in your production environment as part of this process.

Match Rate testing consists of sending a large number of requests to your ecosystem and then measuring how many of the transactions you successfully match to. If your match rate for this test is below 80%, this will need to be resolved before we can promote the integration to production.

You can also request screenshots of test transactions to see how the data renders in the applicable channels, and that the correct information is being displayed in the appropriate manner.

For further guidance and resources regarding testing, please refer to:

* The [Testing](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/testing/index.md) page for instructions about the testing process.
* The [Tutorials and Guides](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/index.md) page for a comprehensive set of integration resources.
* The [Reference Application Tutorial](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/reference-app-tutorial/index.md) page to simulate how your API should interact with Ethoca's Merchant Transaction API.
* The [Gateway Error Codes](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/errors-troubleshooting/gateway-error-codes/index.md) page for the data format of the error codes that can be returned by API.

### Production KPIs {#production-kpis}

To move to production, you must meet the following KPIs and maintain them once live in production:

* **Response Time:** \< 2500ms
* **Transaction Match Rate:** \> 80%
* **Error Rate:** \< 1%
* **Data Availability:** 13 months of transactional data always available within 24 hours of authorization
* **Timeout Percentage (\> 7 second response time):** \< 1%
* **Uptime:** \~99.7%
* **Average Load:** 100 queries per second (qps)
* **Peak Load:** 200 qps

<br />

The KPIs needed for First-Party Trust are the same as the above requirements that support Consumer Clarity products. Please note that, as part of the First-Party Trust program, you'll be required to send additional data fields. For more information, please see the [Response Field Requirements](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/common-elements-headers/index.md#response-field-requirements).

## Deployment Phase {#deployment-phase}

### Pre go-live {#pre-go-live}

#### API secret key generation {#api-secret-key-generation-1}

Your Ethoca integration contact will provision you with a production-grade secret key, the key ID, and the key version, in order to transition the integration from sandbox to production.

### Production verification {#production-verification}

Once testing is complete, Ethoca will perform any final validation tests required to ensure that your API is fully ready for production, including:

* Connectivity
* Authentication with HMAC signature
* Payload testing with production data
* Fuzzy matching logic testing
* Correct response status codes
* Descriptor validation
* Match Rate testing

### Post go-live {#post-go-live}

#### Monitoring and reporting {#monitoring-and-reporting}

Your Ethoca integration contact will actively monitor the integration and API responses for a period of time to ensure that the service is working as expected. If there are any issues, they will work with you to resolve them.

Once any issues have been resolved and the monitoring period is complete, your Ethoca integration contact will hand over the monitoring of your account to Ethoca's post-onboarding team.

Reporting is made available at an agreed-upon cadence. If additional reporting is needed for your organization, please communicate that to your Ethoca integration contact so that we can address as needed.