# Testing
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/testing/index.md

## Test your Ethoca Alerts for Merchants API Integration {#test-your-ethoca-alerts-for-merchants-api-integration}

Use this page to validate your Ethoca Alerts for Merchants integration before you request Production access. The examples on this page are derived from the published OpenAPI specifications and the existing Sandbox test cases already documented for this API.

## Choose a testing method {#choose-a-testing-method}

You can test the API with any of the following tools:

* [Postman Collection](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/postman-collection/index.md)
* [Insomnia Collection](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/insomnia-collection/index.md)
* [Reference Application](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/reference-app/index.md)
* [Custom API client](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-basics/index.md#how-to-consume-the-api)

## Recommended testing workflow {#recommended-testing-workflow}

Use the following sequence to validate the full Pull and Outcome flow in Sandbox:

1. Retrieve one available alert with `GET /alerts` using a narrow filter such as `alert_type=CUSTOMERDISPUTE&size=1`.
2. Confirm that the alert payload can be parsed and matched in your system by checking identifiers such as `alertId`, `merchantId`, `authorizationCode`, and card details.
3. Acknowledge successful receipt with `POST /alerts/acknowledges`.
4. Submit a valid business outcome for that alert with `POST /outcomes`.
5. Repeat the flow with a second scenario, such as a confirmed fraud alert or a partial validation failure in a batch response.
6. Run negative tests for invalid dates, duplicate acknowledgements, and invalid credentials.

This workflow gives you coverage across retrieval, acknowledgement, outcome submission, filtering, batch handling, validation behavior, and OAuth authentication failure handling.

## Positive testing {#positive-testing}

Positive testing validates that successful requests return the expected status codes, that pulled alerts can be acknowledged, that submitted outcomes are accepted, and that the service returns business data in the expected structure.

### Positive test cases {#positive-test-cases}

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

Request example:

```json
{
  "query": {
    "alert_type": "CUSTOMERDISPUTE",
    "size": 1
  }
}
```

Expected result: `200 OK` with an `alerts` array containing one or more alert objects.

Key response details:

```json
{
  "alerts": [
    {
      "alertId": "3EAKPL9SX735ZI9PII18FPQZL",
      "alertTimestamp": "2026-01-12T06:15:13.171792Z",
      "merchantId": "d61391c1-b958-45a3-92ed-bd356cbb8237",
      "merchantName": "submerchant1",
      "alertType": "CUSTOMERDISPUTE",
      "provider": {
        "issuerName": "sample name",
        "source": "issuer"
      }
    }
  ]
}
```

Additional checks:

* Verify that `alertType` matches the query filter.
* Verify that `size=1` limits the returned alert count.
* Verify that the returned alert contains enough transaction identifiers to support merchant-side matching.
* Verify that the response is signed access only and fails without valid OAuth headers.

#### POST /alerts/acknowledges {#post-alertsacknowledges}

Request example:

```json
{
  "alerts": [
    {
      "alertId": "BAUEZHYDNW079TT40P0PXMT2F",
      "status": "SUCCESS"
    }
  ]
}
```

Expected result: `200 OK` with the acknowledged alert listed in `successes`.

Key response details:

```json
{
  "successes": [
    "BAUEZHYDNW079TT40P0PXMT2F"
  ],
  "failures": null
}
```

Additional checks:

* Verify that the acknowledged `alertId` is returned in `successes`.
* Verify that duplicate alerts are not silently accepted.
* Verify that your system stores acknowledgement success before outcome submission begins.

#### POST /outcomes {#post-outcomes}

Request example:

```json
{
  "outcomes": [
    {
      "alertId": "C05XF5HIGYBM883ASUL7VFGCN",
      "outcome": "RESOLVED",
      "refundStatus": "NOT_REFUNDED",
      "refund": {
        "amount": {
          "value": "234.56",
          "currencyCode": "USD"
        },
        "type": "POINTS",
        "timestamp": "2021-01-06T10:30:00.000Z",
        "transactionId": "dhdgjhkhjkhj",
        "acquirerReferenceNumber": "gfgsdfs"
      },
      "amountStopped": {
        "value": "234.56",
        "currencyCode": "USD"
      },
      "comments": "Refunded via transactionId XXX on YYY",
      "actionTimestamp": "2021-01-06T10:30:00.000Z"
    }
  ]
}
```

Expected result: `200 OK` with an `outcomeResponses` array showing `SUCCESS` for the alert.

Key response details:

```json
{
  "outcomeResponses": [
    {
      "alertId": "C05XF5HIGYBM883ASUL7VFGCN",
      "status": "SUCCESS"
    }
  ]
}
```

Additional checks:

* Verify that the alert-specific result is returned in `outcomeResponses`.
* Verify that valid customer dispute outcomes are accepted.
* Verify that a batch with only mandatory fields also succeeds.
* Verify that up to 25 outcomes can be submitted in one request.

## Endpoint tutorials {#endpoint-tutorials}

For end-to-end endpoint walkthroughs and setup guidance, see the tutorials under [Tutorials and Guides](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/tutorials-and-guides/index.md).

## Negative testing {#negative-testing}

Negative testing validates that the API rejects malformed requests, invalid credentials, duplicate acknowledgement attempts, and incomplete outcome data in a predictable way.

### Negative test cases {#negative-test-cases}

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

Request example:

```json
{
  "query": {
    "from_date": "2026-101-209",
    "to_date": "2026-21-20"
  }
}
```

Expected result: `400 Bad Request` because the date format does not match the documented `YYYY-MM-DD` pattern.

Example error details:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "alerts-delivery",
        "ReasonCode": "VALIDATION_FAILURE",
        "Description": "Invalid date format: 2026-101-209",
        "Recoverable": true,
        "Details": "Invalid date format: 2026-101-209"
      }
    ]
  }
}
```

Additional checks:

* Verify that future dates also return validation failures.
* Verify that missing OAuth credentials produce `401 Unauthorized` instead of a validation error.
* Verify that invalid client credentials return the documented gateway error envelope.

#### POST /alerts/acknowledges {#post-alertsacknowledges}

Request example:

```json
{
  "alerts": [
    {
      "alertId": "A325XNZL50FSRX08LMG7DZZOB",
      "status": "SUCCESS"
    },
    {
      "alertId": "A325XNZL50FSRX08LMG7DZZOB",
      "status": "SUCCESS"
    }
  ]
}
```

Expected result: `400 Bad Request` because the same alert is acknowledged more than once in the same request.

Example error details:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "alerts-delivery",
        "ReasonCode": "VALIDATION_FAILURE",
        "Description": "Acknowledge should be Unique",
        "Recoverable": true,
        "Details": "Acknowledge should be Unique"
      }
    ]
  }
}
```

Additional checks:

* Verify that mixed valid and invalid acknowledgements return both `successes` and `failures` when appropriate.
* Verify that invalid OAuth credentials return `401 Unauthorized`.
* Verify that invalid status values are rejected or returned as failures at the item level.

#### POST /outcomes {#post-outcomes}

Request example:

```json
{
  "outcomes": [
    {
      "alertId": "C03XF5HIGYBM883ASUL7VFGCN",
      "outcome": null,
      "refundStatus": "REFUNDED",
      "refund": {
        "amount": {
          "value": "234.56",
          "currencyCode": "USD"
        },
        "type": "POINTS",
        "timestamp": "2021-01-06T10:30:00.000Z",
        "transactionId": "dhdgjhkhjkhj",
        "acquirerReferenceNumber": "gfgsdfs"
      },
      "amountStopped": {
        "value": "234.56",
        "currencyCode": "USD"
      },
      "comments": "Refunded via transactionId XXX on YYY",
      "actionTimestamp": "2021-01-06T10:30:00.000Z"
    },
    {
      "alertId": "C01XF5HIGYBM883ASUL7VFGCN",
      "outcome": "STOPPED",
      "refundStatus": "REFUNDED",
      "refund": {
        "amount": {
          "value": "234.56",
          "currencyCode": "USD"
        },
        "type": "POINTS",
        "timestamp": "2021-01-06T10:30:00.000Z",
        "transactionId": "dhdgjhkhjkhj",
        "acquirerReferenceNumber": "gfgsdfs"
      },
      "amountStopped": {
        "value": "234.56",
        "currencyCode": "USD"
      },
      "comments": "Refunded via transactionId XXX on YYY",
      "actionTimestamp": "2021-01-06T10:30:00.000Z"
    }
  ]
}
```

Expected result: `200 OK` with a mixed batch result showing one failed item and one successful item.

Example response details:

```json
{
  "outcomeResponses": [
    {
      "alertId": "C03XF5HIGYBM883ASUL7VFGCN",
      "status": "FAILED",
      "errorList": [
        {
          "Source": "alerts-outcome",
          "ReasonCode": "REQUEST_VALIDATION_FAILURE",
          "Description": "outcome is mandatory",
          "Recoverable": true,
          "Details": "Invalid outcome value 'null' - outcome is mandatory"
        }
      ]
    },
    {
      "alertId": "C01XF5HIGYBM883ASUL7VFGCN",
      "status": "SUCCESS"
    }
  ]
}
```

Additional checks:

* Verify that a missing mandatory field fails only the invalid item when batch processing allows partial success.
* Verify that invalid credentials return `401 Unauthorized`.
* Verify that invalid enumerations for `outcome` or `refundStatus` produce clear validation details.

### Example error response {#example-error-response}

Most service-level and gateway-level failures use an `Errors` envelope containing one or more `Error` objects.

```json
{
  "Errors": {
    "Error": [
      {
        "ReasonCode": "DECLINED",
        "Description": "Unauthorized - Access Not Granted",
        "Recoverable": false,
        "Details": null,
        "Source": "Gateway"
      }
    ]
  }
}
```

For the complete list of status codes, reason codes, and service-specific validation errors, see [Codes and Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/code-and-formats/index.md).

## Next steps {#next-steps}

* Consult the [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/api-reference/index.md) for complete endpoint specifications, request and response schemas, and environment URLs.
* If you run into issues, visit [Support](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/support/index.md) for FAQs and troubleshooting guidance.