# Guide to API Fields for the Merchant Transaction API source: https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/tutorials-and-guides/api-fields-guide/index.md You can use Ethoca's Merchant Transaction API to provide information for multiple products and programs with a single integration. Each product and program might have different purposes, so it's important to provide the fields that add value to each one. These fields can vary based on the industry in which your organization operates. * For the **Digital Receipt** product, a cardholder sees the digital receipt through the issuing bank's mobile or online banking application, so we won't display fields that might be considered Personally Identifiable Information (PII), such as an email address. * With the **Call Center** product, a cardholder doesn't have access to the information being provided, but the call center agent does. * For **First-Party Trust** , the information is provided internally, but can be displayed to a call center agent should the cardholder inquire about a dispute. This appendix shows the specific Merchant Transaction API objects and associated field IDs that are used by the various services to support multiple products. Note: Fields are required unless otherwise indicated. ## responseStatus {#responsestatus} Shows whether the response received is successful. ```json { "responseStatus": { "code": "MULTIPLE_TRANSACTIONS_FOUND", "message": "Multiple transactions were found for this request.", "trackingId": "zebj8evpeo" } } ``` | Name | Type | Description | minLength | maxLength | |------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------| | code | Alpha Numeric | Enum value that states the result of the request. Possible values are `TRANSACTION_FOUND`, `TRANSACTION_NOT_FOUND`, `MULTIPLE_TRANSACTIONS_FOUND` | 17 | 27 | | message | Alpha Numeric | Provides more details about the result of the request. | 1 | 100 | | trackingId | Alpha Numeric | Any internal reference ID linked to this search. | 1 | 201 | ## merchantProfile {#merchantprofile} Details that identify your company, including name and description about your products or services. You can also provide an absolute URL that lets issuers access your company logo image. ```json { "merchantProfile": { "name": "SHOE STORE 1234", "description": "Austin's largest shoe store", "logoUrl": null, } } ``` | Name | Type | Description | minLength | maxLength | |------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|-----------| | name | Alpha Numeric | Name of the merchant from which the item was purchased. | SHOE STORE 1234 | 1 | | description | Alpha Numeric | Description of the primary merchant tied to the transaction and responsible for providing the products or services (description of the business, what they do, markets, etc.). Used to help cardholder understand business responsible for the charge. | Austin's largest shoe store | 1 | | logoUrl optional | Instance | A URL pointing to your company logo. | https://content.ethoca.com/merchant/ethoca-logo.png | 1 | ## merchantCustomerServiceContact {#merchantcustomerservicecontact} Details about your company's customer service department. ```json { "merchantCustomerServiceContact": { "address": "1234 Main St, Austin, TX, 78701", "phoneNumber": "(800) 555-1234", "email": "ethoca-qa-6@ethoca.com", "website": "https://www.ethoca.com", } } ``` | Name | Type | Description | minLength | maxLength | Example | |------------------|---------------|-----------------------------------------------------------------------------------------------|-----------|-----------|---------------------------------------------------------| | address | Instance | Merchant's customer service contact address | 1 | 100 | 1234 Main St, Austin, TX, 78701 | | phoneNumber | Alpha Numeric | Merchant customer service phone number include the country code and any applicable separators | 3 | 30 | (+1-234-567-8901) | | email optional | Alpha Numeric | Merchant's customer service email address | 1 | 200 | [ethoca-qa-6@ethoca.com](mailto:ethoca-qa-6@ethoca.com) | | website optional | Alpha Numeric | URL for merchant's customer service focused information | 1 | 100 | | ## order {#order} Specific information about the transaction being analyzed, including the item purchased and the credit card used. ```json { "order": { "merchantOrderId": "765656JCHJDJ898HYJY90", "orderDateTime": "2017-06-19T13:18:18Z", "subtotal": "7878.98", "total": "8898.9", "currencyCode": "USD", "orderItems": [ { "id": "898989", "productName": "Monitor", "productDescription": "32 Inches Wide Screen", "quantity": "2", "unitOfMeasurement": "lbs", "productPrice": "890.79", } ], "payments": [ { "id": "3", "matchedPayment": true, "paymentType": "MC", "cardLastFour": "1234", } ], "refunds": [ { "id": "23", "referenceNumber": "89U897Y09K5", "refundDateTime": "2017-06-19T13:18:18Z", "total": "787.96", } ] } } ``` Here are the field IDs used by the `Order` service. | Name | Type | Description | minLength | maxLength | Example | |-----------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------|-----------------------| | merchantOrderId | Alpha Numeric | Merchant internal order tracking number. Usually assigned by eCommerce/ Store system. | 1 | 50 | 765656JCHJDJ898HYJY90 | | orderDateTime | Alpha Numeric | Date of historical order using a string-based date/time representation in international date time format (ISO 8601) in UTC (yyyy-mm-ddThh:mm:ssZ). | 20 | 20 | 2017-06-19T13:18:18Z | | subtotal | Amount Type | Order Subtotal before Tax. Summary amount of all products purchased in this order. Tax and Shipping are not included in this amount. | 1 | 12 | 7878.98 | | tax | Amount Type | Total Tax Amount | 1 | 12 | 1019.92 | | total | Amount Type | Order Total Amount | 1 | 12 | 8898.9 | | currencyCode | Alpha Numeric | Currency applied to order. This currency will apply to all amount/price fields throughout entire payload, must be three character ISO currency code () | 3 | 3 | USD | ### orderItem {#orderitem} | Name | Type | Description | minLength | maxLength | Example | |--------------------|---------------|----------------------------------------------------------------------------------------------------------------------|-----------|-----------|-----------------------| | id | Alpha Numeric | Order Item unique identifier (merchant generated sequence based ID for each order item - For example, 1, 2, 3, 4...) | 1 | 100 | 898989 | | productName | Alpha Numeric | Name of the product | 1 | 100 | Monitor | | productDescription | Alpha Numeric | Description of item, which can contain extended details of the product. For example, size: 6, color: blue | 1 | 1000 | 32 Inches Wide Screen | | quantity | Integer | Quantity of items purchased (1,3,30,) etc. | 1 | 100 | 12 | | unitOfMeasurement | Amount Type | The unit of measurement for the product purchased | 1 | 100 | lbs | | productPrice | Amount Type | Price Per Unit | 1 | 12 | 890.79 | ### payment {#payment} | Name | Type | Description | minLength | maxLength | Example | |----------------|---------------|-----------------------------------------------------------------------------------------------------------------------|-----------|-----------|---------| | id | Alpha Numeric | Payment object unique identifier (merchant generated sequence based ID for each payment - For example, 1, 2, 3, 4...) | 1 | 100 | 3 | | matchedPayment | boolean | Indicates whether a payment record matches the transaction search attributes, either true or false. | n/a | n/a | true | | paymentType | Alpha Numeric | The card brand or network as provided by the issuer. Allowed values: * MC * VISA * AMEX * DISCOVER | 2 | 8 | MC | | cardLastFour | Alpha Numeric | Last four digits of the card used in the transaction. | 4 | 4 | 1234 | ### refund {#refund} | Name | Type | Description | minLength | maxLength | Example | |-----------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------|-----------|----------------------| | id | Alpha Numeric | Refund object unique identifier (merchant generated sequence based ID for each refund) | 1 | 100 | 23 | | referenceNumber | Alpha Numeric | Refund reference number, identifier, or reference number provided by acquirer. This will be hidden from the cardholder. | 1 | 65 | 89U897Y09K5 | | refundDateTime | Alpha Numeric | Date of historical order using a string-based date/time representation in international date time format (ISO 8601) in UTC (yyyy-mm-ddThh:mm:ssZ). | 20 | 20 | 2017-06-19T13:18:18Z | | total | Amount Type | Total Amount that was refunded on the transaction. | 1 | 12 | 787.96 | ## First-Party Trust fields {#first-party-trust-fields} The following fields are part of the Merchant Transaction API. If you're participating in the First-Party Trust program, you must send some or all of these fields, depending on what your organization has access to. For more information about these Compelling Evidence categories, please see [API Request/Response Common Elements and Headers](https://developer.mastercard.com/ethoca-consumer-clarity-for-merchants/documentation/api-basics/common-elements-headers/index.md#response-field-requirements). | Name | Type | Description | minLength | maxLength | |------------------------|--------|--------------------------------------------------------------------------------------------------------------------------|-----------|-----------| | orderPhone | string | Customer phone number for the order. | 3 | 30 | | orderEmail | string | Customer email address for the order/transaction. | 1 | 200 | | deviceIpAddress | string | Device IP address of the purchase. | 1 | 45 | | imeiId | string | Device IMEI ID. | 1 | 32 | | iccId | string | SIM card identifier (integrated circuit card identifier). Stored in the SIM card and engraved on the outside. | 1 | 22 | | orderDeviceId | string | ID of the device used to place order. | 1 | 40 | | orderDeviceName | string | Name of the device used to place order. | 1 | 20 | | orderDeviceFingerprint | string | The fingerprint of the device used for the transaction. | 20 | 200 | | geoLatitude | string | The Latitude of the device used during the transaction. | 1 | 30 | | geoLongitude | string | The Longitude of the device used during the transaction. | 1 | 30 | | shippingAddress | object | Address where the product was delivered to. | object | object | | billingAddress | object | Address where the transaction was billed to. | object | object | | userIdName | string | Merchant unique identifier for customer (if email address is used as the User ID, this field should still be populated). | 1 | 65 |