# Release History
source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/release-history/index.md

## Recent API Updates {#recent-api-updates}

Here you can find details about changes that were recently made to the Merchant Transaction API.

### December 16, 2025 - Improved text across Developers Portal {#december-16-2025---improved-text-across-developers-portal}

We've refreshed the wording throughout the portal to enhance clarity, consistency, accuracy, and readability (including adding more definition about required/highly recommended fields). These updates improve the overall experience but do not change the underlying information or require any API updates.

## Previous API Updates {#previous-api-updates}

The [Getting Started](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md) page has been enhanced into a more robust implementation guide, with more content depth and clarity, clearer links in the process steps, and a new end-to-end map of the integration process.

The [Merchant Transaction API Data Dictionary](https://static.developer.mastercard.com/content/ethoca-consumer-clarity-for-merchants/uploads/merchant-data-dictionary.xlsx) has been updated to be more readable and easier to filter, and to ensure that the list of fields in the Data Dictionary is synchronized with the list of fields in the API spec.

The [Transaction Matching Guidance](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/transaction-matching-guidance/index.md) page has been refined with more content depth, including new pseudocodes, an updated flowchart, and the addition of a Merchant Matching Tips section.

The "Data Completeness \> 95%" metric has been updated to "Error Rate \< 1%" on the [Integration and Testing](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/testing/index.md) page and the [Support](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/support/index.md) page FAQs.
We have added the `/merchants/reports` endpoint to the [Merchant Transaction API](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#apis) to provide merchants and merchant partners with real-time feedback about their Clarity requests. The initial release of this endpoint lets you know if a First-Party Trust request resulted in the liability shifting to the issuer. We have added the `/merchants/notifications` endpoint to the [Merchant Transaction API](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#apis) to provide merchants and merchant partners with real-time feedback about their Clarity integration and requests. The initial release of this endpoint lets you know if a descriptor wasn't onboarded because it already exists in our database. We have added the following fields to enhance the transaction-level API details that are available.

The clearingDateTime, clearingAmount, and clearingCurrency fields allow you to provide transaction information from the time of settlement.

The transactionCategory indicates whether the call was for the initial dispute in question or if it is a historical supporting transaction.

The disputeId field provides an identifier that links all initial and historical requests for one transaction. The disputeIdType field describes the type of disputeId. Both of these fields are First-Party Trust specific.

For more information, please see [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md).
The following updates have been made to the Merchant Transaction API specification:

* To improve transaction match rates, we added three new fields to the Request Criteria: `clearingDateTime`, `clearingAmount`, and `clearingCurrencyCode`. These fields are populated with information about when a transaction is cleared.

  These new fields are different from the current `transactionDateTime`, `transactionAmount`, and `transactionCurrencyCode` fields, as those fields contain the values present at authorization or the moment the transaction occurs. These fields can sometimes be the same, but in instances of drop shipments, differences in foreign exchange rates, or delayed clearing, these values might be different.
* Previously, `unitOfMeasurement` was required as part of the `OrderItem` object. Now, it's no longer a required field.

#### Additional update {#additional-update}

**Note** : We have updated the email address for production support to our [Customer Delivery Team](mailto:customerdelivery@ethoca.com). The email address in the API specification is updated now as well.
We have added the [Merchant Actions Endpoint](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#apis) to the Merchant Transaction API. This new endpoint helps cardholders who want to modify their subscriptions in their banking application.

The integration for merchants will remain the same as it is today for all integrations, but the endpoint will have different functionality, and your response will be different. For more information, see the [Guide to Subscription Controls for Merchants](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/subscription-control-guide/index.md).
To better align with Mastercard's First-Party Trust program, we have added a new field called `orderDeviceFingerprint` to help eliminate any confusion around the device identifier fields. Additionally, we have added a Line 3 to all address objects to better support addresses outside of North America.

Finally, we have updated the descriptions of all IP address fields to be more specific about the data we're requesting.

Check out [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md) for more information about these new fields.
Two new fields are added to the Merchant Transaction API spec that capture the cardholder's latitude and longitude at the time the original transaction is placed. The new fields are `transactionDetails.geoLocationLatitude` and `transactionDetails.geoLocationLongitude` and can be used to provide compelling evidence for the Mastercard First-Party Trust program.

Check out the [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md) for more information about these new fields.
The Merchant Transaction API is now available at the [Mastercard Developer Portal](https://developer.mastercard.com/apis). For more information about specific functionality, see these topics:

* You can review the V4 API specification at [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md).
* The [Quick Start Guide](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/quick-start-guide/index.md) helps you quickly create a new project and generate the keys you need to access the sandbox environment.
* The [Reference App Tutorial](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/reference-app-tutorial/index.md) provides step-by-step guidance for testing your API with requests made by the Merchant Transaction API in a sandbox environment.

## Next Steps {#next-steps}

* Check out [Upcoming API Updates](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/announcements/index.md#upcoming-api-updates) to see if there are any planned changes to the API.
* Review the [Getting Started](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md) article to learn about the basics required for creating an API that can connect to our platform.