# Release History source: https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md ## Recent API Updates {#recent-api-updates} Here you can find details about changes that were recently made to the Consumer Clarity and Smart Subscriptions APIs. ### March 9, 2026 - The acquirerReferenceId field is enabled {#march-9-2026---the-acquirerreferenceid-field-is-enabled} The `acquirerReferenceID` (ARID) is now enabled for an acquirer to use to group related transactions. An acquirer can assign multiple ARIDs, and each ARID may link to several Acquirer Reference Numbers (ARNs). As a best practice, each cleared transaction should still have its own unique ARN. For a description and example of `acquirerReferenceId`, see the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). ### March 9, 2026 - Two fields renamed that help identify transaction origination {#march-9-2026---two-fields-renamed-that-help-identify-transaction-origination} These two fields have been renamed in the Consumer Clarity API `transactionCriteria` object to highlight that the data fields are card agnostic: * `cardPresenceCode` is renamed to `storedCredentialUsage` * `transactionInitiator` is renamed to `storedCredentialInitiator` `storedCredentialUsage` indicates how a stored payment credential is used for the transaction, such as recurring, installment, or unscheduled. And `storedCredentialInitiator` indicates whether the transaction was initiated by the cardholder or by the merchant using a stored credential. For complete descriptions and examples of these two new fields, see the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). If you have questions, contact your [Ethoca Customer Success team](mailto:customerservice@ethoca.com) for more details. ## Previous API Updates {#previous-api-updates} We have re-branded the Subscription Controls service to **Smart Subscriptions** to better reflect the value and simplicity of the service. The new name, **Smart Subscriptions**, emphasizes convenience and control, making it easier for cardholders to recognize and manage their subscriptions in one place. The documentation has been updated with this change. A new article is added that includes key field definitions and provides guidance on required, recommended, or optional fields. For more information, see [Field Recommendations](https://developer.mastercard.com/consumer-clarity/documentation/api-basics/common-elements-headers/index.md). These two fields have been added to the Consumer Clarity API to help identify the origination of a transaction. * The field `cardPresenceCode` is used to indicate the origination of a transaction. For example, is the transaction recurring or card-not-present. * The `transactionInitiator` field provides insight into whether the transaction was initiated by the customer or merchant. For complete descriptions and examples of these two new fields, see the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). We added a new field called `receiptRedirect` to the Consumer Clarity API for Digital Receipts. This field supports the External Receipt Indicator and lets you know that the receipt link (url) that's being returned to the cardholder is not an Ethoca-hosted receipt link. This can help you when deciding on the correct user experience to deliver to your cardholders. For a complete description and example of `receiptRedirect`, review the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). We updated the descriptions for the `cardAcceptorLocation` and `cardAcceptorCountryCode` fields to include the wording **Business Required**. This reflects their importance and value, and we recommend that you send these fields with each request. To review the updated descriptions, see the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). You might notice that the [Quick Start Guide](https://developer.mastercard.com/consumer-clarity/documentation/quick-start-guide/index.md) has been moved out of the [Tutorials and Guides](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/index.md) section to just below the main page in our documentation TOC. In addition, the content has been combined with the Getting Started article that was there previously. This reorganization of the documentation flow makes the Quick Start content more prominent to users, which will let them get up and running that much faster. In our Smart Subscriptions service, we now offer the Subscription Hub. Now, users can view and manage their subscriptions in one centralized location within your digital banking application. For more information about the new Subscription Hub, see [Subscription Hub View](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/displaying-subscription-controls/index.md#subscription-hub-view) and our [Tips for Sending Requests](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#provide-payment-id-and-search-criteria-for-subscription-identification). To improve transaction match rates, we added three new fields to the Transaction Criteria: `clearingDateTime`, `clearingAmount:value`, and `clearingAmount:currencyCode`. These fields are populated with the clearing information for a transaction. These clearing fields differ from the `transactionDateTime` and `transactionAmount` fields, which contain the values present at authorization or the moment that the transaction occurs. The new clearing fields provide the Transaction Date/Time and Transaction Amount information for when the transaction is cleared for payment. Both sets of 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. For complete descriptions and examples of the clearing fields, review the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). The number of transactions that you can send in a batch request has increased to 50. Prior to this release, we only accepted up to 25 transactions per request. Sending batch requests only applies to the Consumer Clarity `/searches` and `/backoffice-searches` endpoints. It doesn't impact the `/transaction-data` endpoint for First-Party Trust or the Smart Subscriptions API. For more information about sending batch requests, see [Manage the Number of Requests Sent](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#manage-the-number-of-requests-sent). The `GET` request method is available now in Smart Subscriptions to let you regularly retrieve a list of the `/actions` requests that have been recently updated. The response includes all subscription actions that have moved from the **In Progress** status to a final state, such as **Successful** , **Unsuccessful** , or **Expired**. This lets you proactively notify your users of a status change for their subscription action requests. For more information, see [Retrieve status updates for subscription actions](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#retrieve-status-updates-for-subscription-actions). This update also includes a new object for the Consumer Clarity API called `RecurringPaymentCriteria` to support issuers who perform their own subscription identification. It lets you indicate which transactions are subscriptions that require subscription enrichment in the response. Then, if the merchant is supported by Ethoca's solution, available subscription management actions are returned in the response. For more information, see [Retrieve supported subscription actions for issuer-identified subscription transactions](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#retrieve-supported-subscription-actions-for-issuer-identified-subscription-transactions). We've released a new endpoint called `/transaction-data` for the Consumer Clarity API. This endpoint provides an issuer or issuer partner with the compelling evidence that Ethoca receives from a merchant as part of Mastercard's First-Party Trust program. Prior to this release, this compelling evidence was only available in the URL that's returned from a POST call to the `/backoffice-searches` endpoint. See these articles for more information about the `/transaction-data` endpoint: * [Provide transaction criteria for First-Party Trust](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#provide-transaction-criteria-for-first-party-trust) provides suggestions on the request data you can send to receive First-Party Trust compelling evidence. * [Use Case in the Call Center Channel](https://developer.mastercard.com/consumer-clarity/documentation/use-cases/index.md#use-case-in-the-call-center-channel) helps you understand the flow of the `/transaction-data` endpoint. * [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis) provides a description and examples of the `/transaction-data` endpoint. A new field called `paymentMode` is available in the API request and lets you indicate whether a transaction was made with a card present (CP) or with the card not present (CNP). For more information and examples of the `paymentMode` field, see [Provide payment mode](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#provide-payment-mode) in the **Tips for Sending Requests** article. In October 2023, we made a change to the `merchantResult` object in which it's only returned or partially returned if the Merchant Details Service is enabled in your product's configuration. Since then, scenarios can occur where the `merchantResult` object isn't returned, which has occasionally caused confusion for some users. To more clearly indicate why merchant information hasn't been provided for these cases, the `ResultStatus` response object now returns the following new codes and messages for `searchResults` and `merchantResult`. These changes apply to both the `/searches` and `/backoffice-searches` endpoints: #### SearchResults {#searchresults} | Scenario | ResultStatus Code | ResultStatus Message | |-------------------------------------------|-------------------|------------------------------------------------------------------------------------| | No Consumer Clarity services are enabled. | `OK` | Please contact your Integration Team or Account Manager to configure your service. | #### MerchantResult {#merchantresult} | Scenario | ResultStatus Code | ResultStatus Message | |---------------------------------------------------------------------------------------------------------------|---------------------------------------------|-----------------------------------------------------------| | An empty `merchantResult` is returned in the response due to suppressed merchant details on a found merchant. | `MERCHANT_FOUND_BUT_DETAILS_NOT_ACCESSIBLE` | Merchant details service not configured for this account. | | `merchantResult` is returned but with suppressed merchant details in the response. | `MERCHANT_FOUND_BUT_DETAILS_NOT_ACCESSIBLE` | Merchant details service not configured for this account. | See [Code and Formats](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md) for detailed information about all error response handling for the Consumer Clarity API. Beginning January 2024, we are now updating the Clarity API and Smart Subscriptions versions for each change to the API specification. This lets you more easily tell when a change has been made. The numbering convention is `major.minor.patch` and is compatible with [Semantic Versioning 2.0.0](https://semver.org/). Note that any API spec prior to January 2024 all share the same version number. The `phone`, `email`, and `contactUrl` fields in the **Consumer Clarity API** response data, that had earlier been deprecated, are now removed from the API specification. These were placeholders for future enhancements and currently no data is returned for these fields in the API. There is no impact to existing customers. A new field called **cardAcceptorId** is now available in the request data to help identify a store location or transaction point. The field is optional and supports Mastercard's upcoming [First Party Trust program](https://www.mastercard.com/news/press/2023/october/mastercard-targets-friendly-fraud-to-protect-small-businesses-and-merchants/), which will help provide more information for merchants to use to match transactions. Previously, the `MerchantResult` object was returned in the response for all API requests. However, not all customers using the API need to leverage the data fields in this object based on their product selection. Now, the `MerchantResult` object is only returned or partially returned based on your product configuration during integration. There's no impact to existing customers and no action is needed as a result of this update. Test cases for the **Smart Subscriptions** product are now available for use when you're testing the functionality in sandbox. See [Smart Subscriptions Test Cases](https://developer.mastercard.com/consumer-clarity/documentation/testing/test-cases-subscription-controls/index.md) for more information. The **Smart Subscriptions** product is now available in the Consumer Clarity API. A new `recurringPaymentKey` object and `/consumer-clarity/subscriptions` API endpoint let you offer cardholders the ability to view their subscription transactions in your banking app and cancel them if needed. See [Display Smart Subscriptions](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/displaying-subscription-controls/index.md) for tips and information about how you can display the Smart Subscriptions response data in your banking app. A new field called `sensitiveContentTypes` is now returned as part of the `merchantResult` object. This field returns any sensitive content types a merchant might have, including `ADULT_LANGUAGE`, `ADULT_PRODUCTS`, `ADULT_SERVICES`, `GAMBLING`, `ONLINE_DATING`, and `OTHER`. This indicates that a merchant might sell products and services containing the returned sensitive content. However, it doesn't mean that all transactions under a particular merchant contain such content. This field is intended to provide you with flexibility in displaying the digital receipts of merchants with sensitive content to your cardholders. Not all merchants have a sensitive content type categorization. Only those merchants categorized as sensitive return the value. Sometimes, a merchant can't return transaction data because the request is outside of their available timeframe. So we now include response codes to provide this information. The `ResultStatus` response object now returns the following new codes and messages for both `purchaseReceipt` and `callCenterDetails`: | Scenario | ResultStatus Code | ResultStatus Message | |---------------------------------------------|-----------------------|---------------------------------------------------------------------------------------------------------| | Transaction is being determined as too new. | `TRANSACTION_TOO_NEW` | The Purchase Receipt is not available because the transaction is too new. Please retry at a later time. | | Transaction is being determined as too old. | `TRANSACTION_TOO_OLD` | The Purchase Receipt is not available because the transaction is older than expected. | | Transaction is being determined as too new. | `TRANSACTION_TOO_NEW` | Call Center Details are not available because the transaction is too new. Please retry at a later time. | | Transaction is being determined as too old. | `TRANSACTION_TOO_OLD` | Call Center Details are not available because the transaction is older than expected. | See [Code and Formats](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md) for detailed information about error response handling for the Consumer Clarity API. A new object called `intermediary` is now included in the response data. The `intermediary` object indicates whether an entity other than the merchant is involved with a transaction. Examples of an `intermediary` can be a payment facilitator (such as PayPal or Square), or a marketplace (such as Amazon or Etsy). Note: Initially, the only `intermediary` object returned is for `type` = *payment facilitator* and `name` = *PayPal*. For more information about how you can use the data returned by the new fields, see [Display Information for an Intermediary](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/displaying-merchant-details/index.md#display-information-for-an-intermediary). A new field called `recordId` is now included in the response and will help you when troubleshooting problems with the [Ethoca Customer Success team](mailto:customerservice@ethoca.com). The new field is applied to each individual response within a bulk request. For example, if there are 25 transactions in a request, there are 25 `recordId` values returned. When troubleshooting an issue with the [Ethoca Customer Success team](mailto:customerservice@ethoca.com), you can reference the specific `recordId` for the problem response. See the [API Reference Specification](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis) for information and an example of the `recordId` field. A new field called `countryName` is now returned as part of the `address` field in the `merchantResult` object. Before, only the `countryCode` was returned in the response data. Now, the name of the country associated with the country code is also returned. For information about the new field, see the [API Reference Specification](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md#apis). You can now sign up to receive carbon footprint information for consumer transactions in your response data through Consumer Clarity. Then, if available, a carbon score is returned in the `carbonFootprint` API response object in the `carbonEmissionInGrams` and `carbonEmissionInOunces` fields. This lets you share with your cardholders the environmental impact of their spending. For detailed information about how to sign up and how to use the data returned by the new fields, see [Display a Carbon Footprint Score](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/displaying-merchant-details/index.md#display-a-carbon-footprint-score). A new field called `type` was added to the `merchantLocation` object. 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. Previously, we were only able to accept five transactions per request. Due to additional testing, we can now accept a batch request of up to 25 transactions. For more information, review the section on [Managing the Number of Requests Sent](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/tips-for-sending-requests/index.md#manage-the-number-of-requests-sent). A new object called `dataPolicyConsent` lets you agree to receive merchant data from a third-party that might provide more enriched details about a merchant. You can review the new object in the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-referenceh/index.md#apis). You can also check out some tips for [How to Use the dataPolicyConsent Response Data](https://developer.mastercard.com/consumer-clarity/documentation/tutorials-and-guides/how-to-use-response-data/displaying-merchant-details/index.md#use-the-datapolicyconsent-response-data). The URL endpoint for the Consumer Clarity API was changed from **enriched-transactions** to **consumer-clarity**. The new endpoints are as follows: * * The Consumer Clarity Receipt Add On service is now available. If you have signed up for the service through our [Customer Delivery Team](mailto:customerdelivery@ethoca.com), you'll be able to add it to your new or existing Consumer Clarity API project. See our [Quick Start Guide](https://developer.mastercard.com/consumer-clarity/documentation/quick-start-guide/index.md) for steps on how you can onboard to the new service. The URL endpoint for the Consumer Clarity API was changed from **api.mastercard.com** to **api.ethocaweb.com** . Any projects you created using the **api.mastercard.com** URL are still valid. For now, both URLs point to our API endpoint. In support of Digital Receipts, the following `transactionIdentifierType` enumeration types were deprecated: * MASTERCARD_RETRIEVAL_REF_NUM * VISA_PURCHASE_IDENTIFIER At the same time, these new enumeration types were added: * BANKNET_REF_NUM * INVOICE_REF_NUM In this section you will find details about the following updates, which were released on January 19, 2021: **API request updates:** * [Locale added](https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md#locale-added) * [Payment type added](https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md#payment-type-added) **API response updates:** * [Result status added](https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md#result-status-added-under-merchant-result-and-purchase-receipt) * [Contact URL added](https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md#contact-url-added) * [Purchase receipt content type added](https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md#purchase-receipt-content-type-added) ### Updates to API request {#updates-to-api-request} #### Locale added {#locale-added} A new required request field, `locale`, is added to support upcoming purchase receipts functionality. The content of the purchase receipt will vary depending on the value in this field. Currently, ten locales are supported for purchase receipts: * `en-CA` (Canadian English) * `en-GB` (United Kingdom English) * `en-ES` (Castilian Spanish) * `en-US` (American English) * `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) ![Properties for locale](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/locale-new.png) Note: At this time, Merchant Result content will continue to be in English regardless of the `locale` value. #### Payment type added {#payment-type-added} A new optional request field, `paymentType`, is added to support upcoming purchase receipts functionality. The value of this field is used by merchants to aide in uniquely identifying a purchase. Currently, four payment types are supported: * `MC` (Mastercard) * `VISA` (Visa) * `AMEX` (American Express) * `DISCOVER` (Discover) ![Properties for payment type](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/paymentType.png) ### Updates to API response {#updates-to-api-response} #### Result status added under merchant result and purchase receipt {#result-status-added-under-merchant-result-and-purchase-receipt} The existing **resultStatus** object, under the **searchResults** object, now returns information related to the overall element. The existing **merchantCriteria** related codes and messages are now included in a new **resultStatus** object under the **merchantResult** object. ![Result status object under merchant result](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/merchant-result-status-new.png) Any **transactionCriteria** related codes and messages are included in a new **resultStatus** object under the **purchaseReceipt** object. ![Result status object under purchase receipt](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/purchase-receipt-new.png) #### Contact URL added {#contact-url-added} A new optional response field, `contactUrl`, is added to support upcoming Consumer Clarity functionality. The value of this field contains the contact URL provided by the merchant. ![Merchant contact URL](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/contact-url.png) #### Purchase receipt content type added {#purchase-receipt-content-type-added} A new required response field, `contentType`, is added to support upcoming purchase receipts functionality. The value of this field designates the type of content expected in the purchase receipt, either purchase-level information (`RECEIPT`) or enhanced merchant details (`MERCHANT_DETAILS`). See the [searchResults.purchaseReceipt: PurchaseReceipt](https://developer.mastercard.com/consumer-clarity/documentation/release-history/index.md#result-status-added-under-merchant-result-and-purchase-receipt) image above for example. Before the most recent API change, the **Logos** schema included only the properties **logoSize** and **logoUrl**. ![Properties for Logos before recent update](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/logo-old.png) Now, values are returned for **height** and **width** (in pixels) and the **url** where the logo image can be accessed. A **type** is returned indicating whether the logo belongs to a merchant or to an industry. And the **altTextTag** is provided for accessibility. ![Properties for Logos after recent update](https://static.developer.mastercard.com/content/consumer-clarity/documentation/img/logo-new-complete.png) ## Next Steps {#next-steps} * Check out [Upcoming API Updates](https://developer.mastercard.com/consumer-clarity/documentation/announcements/index.md#upcoming-api-updates) to see if there are any planned changes to the APIs. * Use the [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md) information for details about the fields and values relevant to your specific needs.