# API Request/Response Common Elements and Headers source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/common-elements-headers/index.md This section details technical requirements for implementing Ethoca's Merchant Transaction API. To facilitate order inquiry collaboration, members of the program will need to expose a web service capable of responding to POST method requests over HTTPS with JSON responses. The POST request body will be sent to you by Ethoca in UTF-8 format as content-type application/json. It will contain metadata properties as well as the order search criteria, formatted as shown below. The API implementation must support shared secret key authorization via an HMAC Authorization header. See [Authentication and Encryption](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/authentication-and-encryption/index.md) for details. Note: If you are enrolled in the First-Party Trust program, the `originatorChannel` field value will be `FIRST_PARTY_TRUST`. ```JSON { "requestReference": { "originatorChannel": "DIGITAL", "originatorId": "420f0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b35304255715f", "sourceId": "66666688ggg0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b324gf", "originatorDescription": "Test Issuer", "correlationId": "zebj8evpeo", "locale": "en-US" }, "searchCriteria": { "paymentType": "MC", "transactionIdentifierType": "BANKNET_REF_NUM", "transactionIdentifierValue": "90989JJJNM7767", "acquirerReferenceNumber": "12345678901234567890123", "transactionDateTime": "2020-06-18T17:11:05-05:00", "cardFirstSix": "123456", "cardLastFour": "1234", "issuerAuthorizationCode": "123456", "transactionAmount": "250.35", "transactionCurrencyCode": "USD", "merchantId": "GHF5F67DFSD468GJJXH78", "cardAcceptorName": "Ethoca Chairs", "cardAcceptorLocation": "Austin", "cardAcceptorRegionCode": "TX", "cardAcceptorCountryCode": "US", "disputeCriteriaDisputeId": "52318413-bd05-4960-a745-f79e5c3d6de9", "disputeCriteriaDisputeIdType": "CLAIM_ID", "clearingDateTime": "2020-11-04T22:11:05.000Z", "clearingAmountValue": "250.35", "clearingAmountCurrencyCode": "USD" } } ``` ## API Request Information {#api-request-information} ### Resource URI and Method {#resource-uri-and-method} The web service endpoint must respond only to POST method requests and the URI must end with the following path: `/api/orders` Note: The path can be prefixed as required to specialize the URI and avoid collisions. For example: `//api/orders` ### Order Search Criteria {#order-search-criteria} The search criteria are used to locate a particular transaction within your database or systems. You'll receive transaction-specific information as input, contained in the POST request body. Using the request fields to search and locate order information that matches the input, the goal is to match the data received to a unique transaction. The fields listed below are sent on most requests. It's possible that different issuers have access to different data points and might not have all of the fields listed. You can configure which fields are required from the issuers and which can be sent optionally. We recommend that you build your matching criteria to receive all fields, regardless of frequency of usage. Additionally, we don't recommend coding to only receive specific fields, as we add new data points for matching on a regular basis. See [Product Requirements](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/testing/index.md#product-requirements) for more information on the desired match rate. #### Search Fields {#search-fields} See the [JSON validation schema in YAML](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md#apis) for detailed descriptions and examples for each parameter. | Field | Description | Example | |------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------| | `transactionDateTime` | This is the authorization date, not the settlement date. Depending on the information you have available, this field would contain: * Date, time, and time zone of transaction authorization in Coordinated Universal Time (UTC) * Date and time of transaction authorization in Coordinated Universal Time (UTC) * Date of transaction authorization in ISO 8601 format (if time and time zone is unknown) | 2020-06-18T17:11:05-05:00 | | `transactionAmount` | Total amount value associated with the transaction at the time of authorization. * Decimal point period is 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.35 | | `cardFirstSix` | The first six digits of the card number associated with the transaction. Must be exactly six numeric characters. | 524167 | | `cardLastFour` | Last four digits of the card used in the transaction. Must be exactly four numeric characters. | 1234 | | `transactionIdentifierValue` | The Transaction ID for this order. The `transactionIdentifierValue` field is highly effective in locating American Express transactions. Definition of values: * **Mastercard:** DE63 * **Visa:** Tran ID or Tran ID1 | T123456 | | `acquirerReferenceNumber` | The Acquirer Reference Number of the transaction. The `acquirerReferenceNumber` field is unique to Mastercard and Visa transactions, and is only available for settled transactions. | 12345678901234567890123 | | `issuerAuthorizationCode` | Issuer authorization code for the transaction. | 123456 | | `merchantId` | The alphanumeric ID of the sub-merchant associated with the purchase details. Required for channel partners. | GHF5F67DFSD468GJJXH78 | | `paymentType` | The card brand or network as provided by the issuer. Allowed values: * **AMEX** (American Express) * **DISCOVER** (Discover) * **MC** (Mastercard) * **VISA** (Visa) | MC | | `transactionCurrencyCode` | Alphabetic currency code associated with the value in ISO 4217 format. | USD | | `transactionIdentifierType` | Payment type-specific transaction identifier type associated with the value specified in `transactionIdentifierValue`. Current values: * BANKNET_REF_NUM * INVOICE_REF_NUM Definition of current values: * **Mastercard:** DE 63, Subfield 2: Banknet Reference Number * **American Express:** TAB Field 26: Invoice/Reference Number | BANKNET_REF_NUM | | `cardAcceptorName` | Merchant 'doing business as' name, or website name * **Mastercard:** DE 43, Subfield 1; Card Acceptor Name * **Visa:** TC 05, positions 92-116; Merchant Name | Ethoca Chairs | | `cardAcceptorLocation` | Merchant city, telephone number, email address, or URL * **Mastercard:** DE 43, Subfield 3: Card Acceptor City * **Visa:** TC 05, positions 117-129: Merchant City | Austin | | `cardAcceptorRegionCode` | Merchant U.S. state code or Canada province code * **Mastercard Clearing:** DE 43, Subfield 5: Card Acceptor State, Province, or Region Code (2-character alpha state or province code defined by ISO 3166-2:US or ISO 3166-2:CA, respectively) * **Mastercard Debit:** DE 43, Subfield 5: Card Acceptor State or Province (2-character alpha state or province code defined by ISO 3166-2:US or ISO 3166-2:CA, respectively) * **Visa Authorization:** Field 59, Positions 1-2: Card Acceptor State or Province Code (2-character numeric state or province code defined by ANSI X3.38) * **Visa Clearing:** TC 05, positions 142-144: Merchant State/Province Code (2-character alpha state or province code defined by ISO 3166-2:US or ISO 3166-2:CA, respectively) | TX | | `cardAcceptorCountryCode` | Merchant country code * **Mastercard Clearing:** DE 43, Subfield 6: Card Acceptor Country Code (3-character alpha country code defined by ISO 3166-1 alpha-3) * **Mastercard Debit:** DE 43, Subfield 5: Card Acceptor Country Code (3-character alpha country code defined by ISO 3166-1 alpha-3) * **Visa Authorization:** Field 43, Positions 39-40: Card Acceptor Country Code (2-character alpha country code defined by ISO 3166-1 alpha-2) * **Visa Clearing:** TC 05, positions 130-132: Merchant Country Code (2-character alpha country code defined by ISO 3166-1 alpha-2) | US | | `clearingDateTime` | Date, time, and time zone of the transaction clearing in Coordinated Universal Time (UTC). | 2020-11-04T22:11:05.000Z | | `clearingAmount` | Total amount value associated with the clearing transaction. | 250.00 | ### Order Search Semantics and Responses {#order-search-semantics-and-responses} It is important to note that at times, you might receive search fields other than your pre-defined search criteria. In these situations, use only the fields that you need. Note: Do not return an error code if any additional fields are sent through with the request. Use the fields necessary to return a unique transaction and ignore any others, in order to accommodate any new fields potentially added in the future. For additional information about which fields to use, see [Transaction Matching Guidance](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/transaction-matching-guidance/index.md). ### Request Message Components {#request-message-components} ```text POST https://:443/api/orders HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Content-Type: application/json Host: User-Agent: Ethoca-purchase-inquirer (version 3.0) X-Eth-Date: 2017-06-19T13:18:18Z Authorization: ETHOCA-SHA1 KeyRef=,Signature= Post request body: { "requestReference": { "originatorChannel": "DIGITAL", "originatorId": "420f0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b35304255715f", "sourceId": "66666688ggg0845bd9b808abd7acc053b0b372ceb461edd584e9b9db02b324gf", "originatorDescription": "Test Issuer", "correlationId": "zebj8evpeo", "locale": "en-US" }, "searchCriteria": { "paymentType": "MC", "transactionIdentifierType": "BANKNET_REF_NUM", "transactionIdentifierValue": "90989JJJNM7767", "acquirerReferenceNumber": "12345678901234567890123", "transactionDateTime": "2020-06-18T17:11:05-05:00", "cardFirstSix": "123456", "cardLastFour": "1234", "issuerAuthorizationCode": "123456", "transactionAmount": "250.35", "transactionCurrencyCode": "USD", "merchantId": "GHF5F67DFSD468GJJXH78", "cardAcceptorName": "Ethoca Chairs", "cardAcceptorLocation": "Austin", "cardAcceptorRegionCode": "TX", "cardAcceptorCountryCode": "US", "disputeCriteriaDisputeId": "52318413-bd05-4960-a745-f79e5c3d6de9", "disputeCriteriaDisputeIdType": "CLAIM_ID", "clearingDateTime": "2020-11-04T22:11:05.000Z", "clearingAmountValue": "250.35", "clearingAmountCurrencyCode": "USD" } } ``` ## API Response Information {#api-response-information} ### Resource Information {#resource-information} Response Format JSON Required Authorization Yes ### Response Compression {#response-compression} To reduce response bandwidth, gzip compression should be enabled. The request will include a header indicating the acceptable content encodings, for example: `Accept-Encoding: gzip, deflate` Use the appropriate response header to indicate the payload compression used, for example: `Content-Encoding: gzip` Note: Content-Type should be `application/json` for both requests and responses. ### Response Field Requirements {#response-field-requirements} We recommend providing all available fields related to your specific vertical domain. Vertical domains include Online Services, Downloaded Products, Physical Goods, and so on. A minimum number of required fields must be provided for your response to be successful. If you don't provide these fields, the message fails and the information won't be provided to the customer or issuer. The required fields are listed in the following table, along with some highly recommended fields to enhance performance: | Field Name | Field Description | Example | |------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | merchantOrderId required | Merchant's internal order tracking number | 765656JCHJDJ898HYJY90 | | orderDateTime required | The date and time the order was made, as a string-based date/time representation in international date time format (ISO 8601) in UTC (yyyy-mm-ddThh:mm:ssZ) | 2017-06-19T13:18:18Z | | subtotal required | Order subtotal. Total amount of all products purchased in this order, not including tax and shipping. The maximum number of fractional digits supported is 2. | 7878.98 | | total required | Total amount of the order, including tax and shipping. Maximum number of fractional digits supported is 2. | 8898.90 | | currencyCode required | Currency code applied to order. This currency will apply to all amount/price fields throughout entire payload. Must be a three character ISO currency code () | USD | | productName required | Name of the product | Monitor | | orderPhone highly recommended | Customer phone number for the order. | +91 99898989800 | | orderEmail highly recommended | Customer email address for the order/transaction. | [onetwothree@example.com](mailto:onetwothree@example.com) | | deviceIpAddress highly recommended | Device IP address of the purchase | 120.0.0.1 | | orderDeviceName highly recommended | Name of the device used to place order. | ETHOCAMAC909 | | shippingAddress highly recommended | Address where the product was delivered to. | See the specifications for more details | | billingAddress highly recommended | Address where the transaction was billed to. | See the specifications for more details | | userIdName highly recommended | Merchant unique identifier for customer (if email address is used as the User ID, this field should still be populated). | testuser123 | | linkUrl highly recommended | Call to Action URL. | https://​support.testmerchant.com/cta | | linkType highly recommended | Call to Action types. Allowed values: * VIEW_ORDER * REQUEST_REFUND * BUY_AGAIN * WRITE_REVIEW | https://​support.testmerchant.com/cta | If you're participating in the First-Party Trust program, you must provide additional information as part of the Compelling Evidence requirements. These fields aren't all mandated; you can decide which fields work best for your organization. But one field from each Compelling Evidence category (**Device Identity Factor** , **Delivery Factor** , **Additional Identity Factor**) must be provided. The following table specifies the fields that are supported: | Field Name | Field Description | Device Identity Factor | Device Factor | Additional Identity Factor | Example | |------------------------|--------------------------------------------------------------------------------------------------------------------------|------------------------|---------------|----------------------------|------------------------------------------------------------------| | orderPhone | Customer phone number for the order. | | ✓ | ✓ | +91 99898989800 | | orderEmail | Customer email address for the order/transaction. | | ✓ | ✓ | [onetwothree@example.com](mailto:onetwothree@example.com) | | deviceIpAddress | Device IP address of the purchase | ✓ | | ✓ | 120.0.0.1 | | imeiId | Device IMEI ID. | ✓ | | ✓ | 987979KHH78798JHJHJ | | iccId | SIM card identifier (integrated circuit card identifier). Stored in the SIM card and engraved on the outside. | ✓ | | ✓ | 56897687870898 | | orderDeviceId | ID of the device used to place order. | ✓ | | ✓ | DAX9090989 | | orderDeviceName | Name of the device used to place order. | | | ✓ | ETHOCAMAC909 | | orderDeviceFingerprint | The fingerprint of the device used for the transaction. | ✓ | | ✓ | a48d8a6de1453c98eefdb906f08e8f1314cc2ec41a20291ab70ff75d47c66a3d | | geoLatitude | The Latitude of the device used during the transaction (no longer than 30 digits). | | | ✓ | 46.4992699 | | geoLongitude | The Longitude of the device used during the transaction (no longer than 30 digits). | | | ✓ | -81.0005857 | | shippingAddress | Address where the product was delivered to. | | ✓ | ✓ | See the specifications for more details | | userIdName | Merchant unique identifier for customer (if email address is used as the User ID, this field should still be populated). | | | ✓ | testuser123 | ### Example Response {#example-response} Payload schema and samples will be provided by your Ethoca integration contact. For an example response, see [API Reference](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-reference/index.md). For details about the status codes you should return in the response, see [Code and Formats](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/code-and-formats/index.md). ## API Health Check Information {#api-health-check-information} A Health or Echo or Heartbeat endpoint ensures that your API is running. ### Resource URI and method {#resource-uri-and-method-1} To facilitate a health check inquiry, you need to expose a web service capable of responding to GET method requests over HTTPS with JSON responses. The web-service endpoint must respond only to GET method requests and the URI must end with the following path: `/api/orders/healthchecks` The path can be prefixed as required to specialize the URI and avoid collisions. For example: `//api/orders/healthchecks` Note: If you specify a ``, it must be the same for both `/api/orders` and `/api/orders/healthchecks`. Ethoca sends a GET request two times each day to monitor the health of your endpoint. ### Response information {#response-information} The web service should return an HTTP 200 OK success status response code indicating that the API is up and running. ## See Also {#see-also} For detailed information about authorization requirements, review [Authentication and Encryption](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/authentication-and-encryption/index.md). ## Next Steps {#next-steps} Now that you have an understanding of the service's common elements and headers, proceed to [Getting Started](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/getting-started/index.md) for step-by-step integration instructions.