# Data Explanations
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/data-explanations/index.md

## Ethoca Alerts for Merchants API Data Dictionary {#ethoca-alerts-for-merchants-api-data-dictionary}

This page provides reference documentation for data elements, field formats, enumerations, and terminology used throughout the Ethoca Alerts for Merchants API.

*** ** * ** ***

## Alert Types {#alert-types}

Ethoca sends two types of alerts:

### CUSTOMERDISPUTE {#customerdispute}

A customer has initiated a chargeback or dispute with their card issuer.

**Key characteristics:**

* Customer claims transaction was unauthorized or incorrect
* Action needed: Contact customer to resolve or document evidence
* Outcome codes: `RESOLVED`, `RESOLVED_PREVIOUSLY_REFUNDED`, `UNRESOLVED_DISPUTE`, `NOT_FOUND`, `OTHER`
* Typical response: Verify with customer, provide receipt/tracking, issue refund if applicable

**Example:**

```json
{
  "alertId": "ALERT_001",
  "alertType": "CUSTOMERDISPUTE",
  "customerName": "Jane Smith",
  "transactionAmount": "150.00",
  "dateSubmitted": "2024-06-23"
}
```

### CONFIRMEDFRAUD {#confirmedfraud}

A card issuer has identified the transaction as fraudulent.

**Key characteristics:**

* Issuer detected fraud signals or customer fraud claim substantiated
* Action needed: Stop the transaction, block the account, issue refund
* Outcome codes: `STOPPED`, `PARTIALLY_STOPPED`, `PREVIOUSLY_CANCELLED`, `MISSED`, `NOT_FOUND`, `ACCOUNT_SUSPENDED`, `OTHER`
* Typical response: Cancel/refund transaction, suspend account, investigate other fraudulent transactions

**Example:**

```json
{
  "alertId": "ALERT_002",
  "alertType": "CONFIRMEDFRAUD",
  "customerName": "John Doe",
  "transactionAmount": "250.00",
  "dateSubmitted": "2024-06-23"
}
```

*** ** * ** ***

## Field Formats {#field-formats}

### Date Formats {#date-formats}

|           Field           |         Format         |                Example                 |                Notes                |
|---------------------------|------------------------|----------------------------------------|-------------------------------------|
| `transactionDate`         | YYYY-MM-DD             | `2024-06-20`                           | Date transaction occurred           |
| `dateSubmitted`           | YYYY-MM-DD or ISO 8601 | `2024-06-23` or `2024-06-23T14:30:00Z` | Date alert was created              |
| `from_date` (query param) | YYYY-MM-DD             | `2024-06-01`                           | Query parameter for alert retrieval |
| `to_date` (query param)   | YYYY-MM-DD             | `2024-06-23`                           | Query parameter for alert retrieval |

**Note:** Always validate date format as YYYY-MM-DD for query parameters. ISO 8601 timestamps in response bodies include timezone.

### Currency Codes {#currency-codes}

All transaction amounts are in ISO 4217 currency codes:

| Code |     Currency      |   Example    |
|------|-------------------|--------------|
| USD  | US Dollar         | `150.00 USD` |
| EUR  | Euro              | `120.00 EUR` |
| GBP  | British Pound     | `100.00 GBP` |
| CAD  | Canadian Dollar   | `180.00 CAD` |
| AUD  | Australian Dollar | `200.00 AUD` |

**Format:** 3-letter uppercase code

### Amount Format {#amount-format}

All monetary amounts are strings in decimal format with up to 2 decimal places:

|             Value              |   Format   | Valid |
|--------------------------------|------------|-------|
| One hundred fifty dollars      | `150.00`   | ✓     |
| One dollar fifty cents         | `1.50`     | ✓     |
| One dollar                     | `1.00`     | ✓     |
| One cent                       | `0.01`     | ✓     |
| One hundred fifty (no cents)   | `150`      | ✓     |
| One hundred fifty (4 decimals) | `150.0000` | ✗     |

**Important:** Always use string type for amounts to preserve precision. Parse with decimal arithmetic, not floating point.

*** ** * ** ***

## Outcome Codes Reference {#outcome-codes-reference}

### CUSTOMERDISPUTE Outcomes {#customerdispute-outcomes}

|              Code              |            Description             |                             Use Case                             |                            Example                            |
|--------------------------------|------------------------------------|------------------------------------------------------------------|---------------------------------------------------------------|
| `RESOLVED`                     | Dispute resolved without refund    | Customer confirmed transaction; merchant provided documentation  | Customer acknowledged purchase after merchant contact         |
| `RESOLVED_PREVIOUSLY_REFUNDED` | Dispute resolved with prior refund | Refund already issued before chargeback filed                    | Refund approved 5 days ago; dispute still filed               |
| `UNRESOLVED_DISPUTE`           | Unable to resolve dispute          | Insufficient merchant evidence or customer insists on chargeback | No receipt available; customer refuses to withdraw dispute    |
| `NOT_FOUND`                    | No matching transaction            | Transaction not in merchant system or declined                   | Alert references non-existent transaction or declined payment |
| `OTHER`                        | Custom outcome                     | Outcome doesn't fit standard codes                               | Partial refund issued; account suspended pending review       |

### CONFIRMEDFRAUD Outcomes {#confirmedfraud-outcomes}

|          Code          |               Description                |                       Use Case                       |                              Example                              |
|------------------------|------------------------------------------|------------------------------------------------------|-------------------------------------------------------------------|
| `STOPPED`              | Fraud transaction successfully blocked   | Preventive action taken before payment cleared       | Fraudster's account suspended within 1 hour of purchase           |
| `PARTIALLY_STOPPED`    | Partial fraud blocked                    | Some transactions in batch stopped; others completed | Fraudster made 5 purchases; merchant refunded 3                   |
| `PREVIOUSLY_CANCELLED` | Transaction cancelled before fraud alert | Merchant cancelled before issuer fraud detection     | Merchant flagged as suspicious; cancelled order before chargeback |
| `MISSED`               | Fraud transaction completed              | Transaction settled before merchant could stop       | Payment cleared 2 days ago; unable to reverse                     |
| `NOT_FOUND`            | No matching transaction                  | Transaction not in system or declined                | Alert references declined authorization attempt                   |
| `ACCOUNT_SUSPENDED`    | Account closed due to fraud              | Fraud account disabled to prevent further abuse      | Account suspended immediately; passwords reset                    |
| `OTHER`                | Custom fraud outcome                     | Outcome doesn't fit standard codes                   | Investigation ongoing; outcome TBD                                |

*** ** * ** ***

## Refund Status Codes {#refund-status-codes}

After submitting an outcome, indicate refund status:

|      Code      |          Meaning          |                                 Use Case                                 |
|----------------|---------------------------|--------------------------------------------------------------------------|
| `REFUNDED`     | Refund issued to customer | Transaction reversed; funds returned                                     |
| `NOT_REFUNDED` | No refund issued          | Dispute resolved without refund or fraud confirmed but unable to reverse |

*** ** * ** ***

## Refund Type Codes {#refund-type-codes}

If `refundStatus` is `REFUNDED`, specify the refund method:

|    Code     |                Meaning                 |                       Example                        |
|-------------|----------------------------------------|------------------------------------------------------|
| `REFUND`    | Cash refund to original payment method | Credit card refunded; funds returned to card account |
| `VOUCHER`   | Merchant credit or gift card           | $150 store credit issued instead of cash refund      |
| `POINTS`    | Loyalty points credited                | 150 reward points credited to account                |
| `GIFT_CARD` | Digital or physical gift card          | $150 e-gift card sent to customer email              |

*** ** * ** ***

## Query Parameter Reference {#query-parameter-reference}

### GET /alerts Parameters {#get-alerts-parameters}

|  Parameter   |        Type         | Required |                Range                | Default  |      Example      |
|--------------|---------------------|----------|-------------------------------------|----------|-------------------|
| `alert_type` | String              | No       | `CUSTOMERDISPUTE`, `CONFIRMEDFRAUD` | All      | `CUSTOMERDISPUTE` |
| `from_date`  | String (YYYY-MM-DD) | No       | Any valid date                      | No limit | `2024-06-01`      |
| `to_date`    | String (YYYY-MM-DD) | No       | Any valid date after from_date      | Today    | `2024-06-23`      |
| `size`       | Integer             | No       | 1--1000                             | Varies   | `50`              |

**Rules:**

* If both `from_date` and `to_date` are provided, `from_date` must be ≤ `to_date`
* If `to_date` is omitted, defaults to current date
* `size` controls pagination; default varies by environment (typically 100--500)

**Example:**

    GET /alerts?alert_type=CONFIRMEDFRAUD&from_date=2024-06-01&to_date=2024-06-23&size=100

*** ** * ** ***

## Response Field Reference {#response-field-reference}

### Alert Fields (Pull API Response) {#alert-fields-pull-api-response}

|         Field         |  Type  |              Description              |      Example       |
|-----------------------|--------|---------------------------------------|--------------------|
| `alertId`             | String | Unique alert identifier               | `ALERT_ID_001`     |
| `alertType`           | String | `CUSTOMERDISPUTE` or `CONFIRMEDFRAUD` | `CUSTOMERDISPUTE`  |
| `transactionAmount`   | String | Amount in decimal format              | `150.00`           |
| `transactionCurrency` | String | ISO 4217 currency code                | `USD`              |
| `dateSubmitted`       | String | Date alert created (YYYY-MM-DD)       | `2024-06-23`       |
| `customerName`        | String | Customer's full name                  | `Jane Smith`       |
| `cardLastFour`        | String | Last 4 card digits                    | `5678`             |
| `merchantName`        | String | Your merchant name                    | `Example Merchant` |
| `transactionRef`      | String | Your transaction reference            | `TXN_REF_001`      |
| `transactionDate`     | String | Transaction date (YYYY-MM-DD)         | `2024-06-20`       |
| `acquirerReference`   | String | Card network reference                | `ACQ_REF_001`      |

### Outcome Request Fields {#outcome-request-fields}

|              Field               |  Type  |  Required   |               Description                |               Example                |
|----------------------------------|--------|-------------|------------------------------------------|--------------------------------------|
| `alertId`                        | String | Yes         | Alert ID from alert response             | `ALERT_ID_001`                       |
| `alertType`                      | String | Yes         | `CUSTOMERDISPUTE` or `CONFIRMEDFRAUD`    | `CUSTOMERDISPUTE`                    |
| `outcomeCodes[].codeType`        | String | Yes         | Always `INVESTIGATION_RESULT`            | `INVESTIGATION_RESULT`               |
| `outcomeCodes[].code`            | String | Yes         | Outcome code (see reference)             | `RESOLVED`                           |
| `refundInformation.refundStatus` | String | Yes         | `REFUNDED` or `NOT_REFUNDED`             | `NOT_REFUNDED`                       |
| `refundInformation.refundType`   | String | Conditional | Required if `refundStatus` is `REFUNDED` | `REFUND`                             |
| `refundInformation.refundAmount` | String | Conditional | Amount if refunded                       | `150.00`                             |
| `comments`                       | String | No          | Investigation notes (max 500 chars)      | `Transaction verified as legitimate` |

*** ** * ** ***

## Error Response Structure {#error-response-structure}

All errors are returned in a standard envelope:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "API",
        "ReasonCode": "VALIDATION_FAILURE",
        "Description": "Invalid date format. Expected YYYY-MM-DD.",
        "Recoverable": false,
        "Details": "Field 'from_date' received '06/23/2024' but expected 'YYYY-MM-DD' format"
      }
    ]
  }
}
```

|     Field     |  Type   |                     Description                      |
|---------------|---------|------------------------------------------------------|
| `Source`      | String  | Error source: `API`, `GATEWAY`, or `SERVICE`         |
| `ReasonCode`  | String  | Machine-readable error code                          |
| `Description` | String  | Human-readable error description                     |
| `Recoverable` | Boolean | `true` if retry is appropriate; `false` if permanent |
| `Details`     | String  | Additional context or hints for resolution           |

*** ** * ** ***

## Common Validation Rules {#common-validation-rules}

### Date Validation {#date-validation}

* `from_date` must be ≤ `to_date`
* Dates must be in YYYY-MM-DD format for query parameters
* Dates must be valid calendar dates (for example, 2024-02-30 is invalid)

### Amount Validation {#amount-validation}

* Amounts must be non-negative
* Maximum 2 decimal places
* String type (not numeric) to preserve precision

### Batch Size Validation {#batch-size-validation}

* Pull API: Alert retrieval max 1,000 items
* Outcome API: Max 25 outcomes per request
* Acknowledgement API: Max 1,000 acknowledgements per request

### Outcome Code Validation {#outcome-code-validation}

* Must match the alert's `alertType`
* `CUSTOMERDISPUTE` alerts cannot use `STOPPED` or `PARTIALLY_STOPPED` codes
* `CONFIRMEDFRAUD` alerts cannot use `RESOLVED` or `RESOLVED_PREVIOUSLY_REFUNDED` codes

### Refund Validation {#refund-validation}

* If `refundStatus` is `REFUNDED`, then `refundType` is required
* If `refundStatus` is `NOT_REFUNDED`, `refundType` and `refundAmount` must be omitted
* `refundAmount` must match the original `transactionAmount` or be less

*** ** * ** ***

## Next Steps {#next-steps}

* Review [Pull API Tutorial](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/data-explanations/pull-api-tutorial.md) for retrieval examples
* See [Push API Tutorial](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/data-explanations/push-api-tutorial.md) for webhook examples
* Check [Outcome API Tutorial](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/data-explanations/outcome-api-tutorial.md) for submission examples
* Visit [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/code-and-formats/index.md) for comprehensive error reference