# Field Recommendations source: https://developer.mastercard.com/consumer-clarity/documentation/api-basics/common-elements-headers/index.md This section details some of the key data fields used in the Consumer Clarity product suite and how they affect API performance. Fields are grouped into three categories: * **Required Fields:** These must be included for the API to process your request successfully. Missing or invalid values will result in an error. * **Recommended Fields:** While not mandatory, these fields are important for achieving accurate matches and optimal product performance. * **Optional Fields:** These can be sent if available but have little impact on API behavior or match rates.
Use this guide to help make sure your integration is error-free and delivers the best possible experience. For a more comprehensive list of fields and their detailed definitions, see the API specifications at [API Reference](https://developer.mastercard.com/consumer-clarity/documentation/api-reference/index.md). Note: The Transaction Data product mentioned on this page includes First-Party Trust. ## Key Fields Definitions {#key-fields-definitions} This table lists some of the key fields to consider when building your API. And [API Required Fields](https://developer.mastercard.com/consumer-clarity/documentation/api-basics/common-elements-headers/index.md#api-required-fields-request) provides guidance on which fields are required, recommended, or optional for specific Consumer Clarity products. | Field Name | Field Description | Example | |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------| | cardAcceptorId | Identifies the card acceptor for the point of the transaction in both local and interchange environments. The value should be unique for each originator for whom you are sending transactions. Defined by ISO 8583, it can be string, length 1 - 15 digits, of any alpha numeric value, and may begin and end with zeros or letters. | CardAcceptor123 | | cardAcceptorName | Merchant 'doing business as' name, or website name. | ETHOCA CHAIRS | | cardAcceptorLocation | Merchant city, telephone number, email address, or URL. | SUNNYVALE | | cardAcceptorRegionCode | The abbreviation for a subdivision (State, Province, Parish, Territory, etc.) provided in the ISO 639-1 and ISO-3166-2 format. | CA | | cardAcceptorCountryCode | Merchant country code. | USA | | merchantCategoryCode | Merchant Category Code (MCC) of the merchant. | 1234 | | acquirerReferenceId | The acquirer reference identifier, used to determine the acquiring issuer. | 531267 | | transactionIdentifierType | Payment type-specific transaction identifier type associated with the value specified in transactionIdentifierValue. | BANKNET_REF_NUM | | transactionIdentifierValue | Transaction identifier value associated with the type specified in transactionIdentifierType. | 123456 | | acquirerReferenceNumber | Acquired Reference Number of the transaction. | 20292029202920292029001 | | transactionDateTime | * Date, time, and time zone of the transaction authorization (e.g., 2020-06-18T17:11:05-05:00), OR * Date and time of the transaction authorization in Coordinated Universal Time (UTC) (e.g., 2020-06-18T17:11:05+00:00), OR * If time or time zone is unknown, then date of the transaction authorization (e.g., 2020-06-18) in ISO 8601 format | 2021-06-18T22:11:05+05:00 | | transactionAmount | Total amount value associated with the transaction. * Decimal point period expected to denote separation of the fractional suffix from the rest of the amount, if applicable for the currency. * Decimal point period must not be the first character. | 361.56 | | currencyCode | Alphabetic currency code associated with value in ISO 4217 format. | USD | | cardFirstSix | First six digits of the card used in the transaction. | 123456 | | cardLastFour | Last four digits of the card used in the transaction. | 5363 | | issuerAuthorizationCode | Transaction's issuer authorization code. | 123456 | | paymentType | Payment type associated with the purchase. | MC | | paymentMode | Indicates if a transaction took place as Card Present or Card Not Present. | CNP | | clearingDateTime | * Date, time, and time zone of the transaction clearing (e.g., 2020-06-18T17:11:05-05:00), OR * Date and time of the transaction authorization in Coordinated Universal Time (UTC) (e.g., 2020-06-18T17:11:05+00:00), OR * If time or time zone is unknown, then date of the transaction authorization (e.g., 2020-06-18) in ISO 8601 format | 2020-11-04T17:11:05-05:00 | | clearingAmount | Total amount value at the time of clearing. * Decimal point period expected to denote separation of the fractional suffix from the rest of the amount, if applicable for the currency. * Decimal point period must not be the first character. | 250.00 | | recurringPaymentType | Type of recurring payment. | SUBSCRIPTION | | merchantName | The name of the merchant. | Ethoca Test Merchant | | serviceName | Brand name of the service. | Ethoca Chairs | | frequency | Frequency of a recurring subscription transaction. | MONTHLY | | disputeId | Unique Identifier of the dispute transaction. | 200002007713 | | disputeType | Type of dispute ID. | CLAIM_ID | | id | Internal ID of the Issuer making an API request. This is a mandatory field in the case of Partners. | 1234 | | name | Name of the Issuer making an API request. This is a mandatory field in the case of Partners. | Ethoca Bank | | userId | User ID of the Agent performing the lookup. Do not include the Agent's First Name, Last Name, or Email Address. | User6789 | | paymentId | Unique ID that is generated by an Issuer to indicate a unique payment instrument. As an example, a cardholder that has 3 cards will have 3 unique payment IDs. Also note this field is not to be confused with card number. Issuers should not send any card information or ID in this field. | 52318413-bd05-4960-a745-f79e5c3d6de9 | ## API Required Fields (Request) {#api-required-fields-request} The following table provides guidance on which key fields are required (❗), recommended (👍), or optional (🔷) for specific Consumer Clarity products. | Field Name | Merchant Details | Digital Receipts | Call Center UI | Transaction Data | Smart Subscriptions | |------------------------------------|------------------|------------------|----------------|------------------|---------------------| | cardAcceptorId | 👍 | 👍 | 👍 | 👍 | 👍 | | cardAcceptorName | ❗ | ❗ | ❗ | ❗ | ❗ | | cardAcceptorLocation | 👍 | 👍 | 👍 | 👍 | ❗ | | cardAcceptorRegionCode | 👍 | 👍 | 👍 | 👍 | ❗ | | cardAcceptorCountryCode | 👍 | 👍 | 👍 | 👍 | ❗ | | merchantCategoryCode | 👍 | 🔷 | 🔷 | 🔷 | 🔷 | | acquirerReferenceId | 👍 | 👍 | 👍 | 👍 | 👍 | | transactionIdentifierType | 🔷 | 👍 | 👍 | 👍 | ❗ | | transactionIdentifierValue | 🔷 | 👍 | 👍 | 👍 | ❗ | | acquirerReferenceNumber | 🔷 | 👍 | 👍 | ❗ | 👍 | | transactionDateTime | 🔷 | 👍 | 👍 | 👍 | ❗ | | transactionAmount (incl. currency) | 🔷 | 👍 | 👍 | 👍 | ❗ | | currencyCode | 🔷 | 👍 | 👍 | 👍 | ❗ | | cardFirstSix | 🔷 | 👍 | 👍 | 👍 | 🔷 | | cardLastFour | 🔷 | 👍 | 👍 | 👍 | 🔷 | | issuerAuthorizationCode | 🔷 | 👍 | 👍 | 👍 | 🔷 | | paymentType | ❗ | ❗ | ❗ | 👍 | 👍 | | paymentMode | 👍 | 👍 | 👍 | 👍 | 🔷 | | clearingDateTime | 🔷 | 👍 | 👍 | 🔷 | 🔷 | | clearingAmount (incl. currency) | 🔷 | 👍 | 👍 | 🔷 | 🔷 | | recurringPaymentType | 🔷 | 🔷 | 🔷 | 🔷 | ❗ | | merchantName | 🔷 | 🔷 | 🔷 | 🔷 | 👍 | | serviceName | 🔷 | 🔷 | 🔷 | 🔷 | 👍 | | frequency | 🔷 | 🔷 | 🔷 | 🔷 | 👍 | | disputeId\* | 🔷 | 🔷 | ❗ | ❗ | 🔷 | | disputeType\* | 🔷 | 🔷 | ❗ | ❗ | 🔷 | | (requestor) id\*\* | 👍 | 👍 | 👍 | 👍 | 👍 | | (requestor) name\*\* | 👍 | 👍 | 👍 | 👍 | 👍 | | (requestor) userId\*\* | 👍 | 👍 | 👍 | 👍 | 👍 | | paymentId | 🔷 | 🔷 | 🔷 | 🔷 | ❗ | \*Required for the Transaction Data product. \*\*Required for Partners.