# Postman Collection
source: https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/postman-collection/index.md

A pre-configured Postman collection is available for Ethoca Alerts for Merchants. It includes all endpoints with OAuth 1.0a authentication setup, environment variables, request/response examples, and test scripts.

*** ** * ** ***

## Downloading the Collection {#downloading-the-collection}

The collection is available in two formats:

**Option 1: Import via Postman Link**

1. Open [Postman](https://www.postman.com)
2. Click **Import** → **Link** → enter the collection URL below
3. Select **Ethoca Alerts for Merchants** → **Import**

**Option 2: Download and Import Manually**

* Download: [ethoca-alerts-for-merchants-collection.json](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/uploads/ethoca-alerts-for-merchants-postman.json)
* Open Postman → **File** → **Import** → Select the downloaded file

*** ** * ** ***

## Environment Setup {#environment-setup}

The collection uses environment variables to store credentials and URLs. You must configure these before running requests.

### Step 1: Create an Environment {#step-1-create-an-environment}

1. In Postman, click **Environments** (left sidebar)
2. Click **Create New** → Name it `Ethoca Sandbox` (or `Ethoca Production`)
3. Add the following variables:

|      Variable       |  Type  |                        Sandbox Value                        |                  Production Value                   |
|---------------------|--------|-------------------------------------------------------------|-----------------------------------------------------|
| `base_url`          | String | `https://sandbox.api.ethocaweb.com/ethoca/alerts/merchants` | `https://api.ethocaweb.com/ethoca/alerts/merchants` |
| `consumer_key`      | String | Your Sandbox consumer key                                   | Your Production consumer key                        |
| `keystore_path`     | String | `/path/to/your/sandbox.p12`                                 | `/path/to/your/production.p12`                      |
| `keystore_password` | String | Your keystore password                                      | Your keystore password                              |
| `keystore_alias`    | String | Your key alias                                              | Your key alias                                      |

**Important:** Mark sensitive fields (consumer_key, keystore_password, keystore_alias) as **Secret** to hide them in the interface.

4. Click **Save**

### Step 2: Select the Environment {#step-2-select-the-environment}

1. In Postman, click the **Environment** dropdown (top right)
2. Select **Ethoca Sandbox** (or **Ethoca Production**)

*** ** * ** ***

## OAuth 1.0a Configuration {#oauth-10a-configuration}

The collection uses Postman's built-in OAuth 1.0a support. For each request, OAuth headers are automatically generated.

### Configuring OAuth in Requests {#configuring-oauth-in-requests}

Each request in the collection is pre-configured with OAuth 1.0a. To verify or modify the configuration:

1. Open a request (for example, `GET /alerts`)
2. Click the **Authorization** tab
3. Verify the Type is set to **OAuth 1.0a**
4. Check that the following fields reference your environment variables:
   * **Consumer Key:** `{{consumer_key}}`
   * **Keystore:** `{{keystore_path}}`
   * **Keystore Password:** `{{keystore_password}}`
   * **Key Alias:** `{{keystore_alias}}`

If these are not set, manually configure them:

1. In the Authorization tab, set Type to **OAuth 1.0a**
2. Enter the values from your Environment variables
3. Click **Update Request** to apply

### Generating Signatures {#generating-signatures}

When you click **Send**, Postman automatically generates the OAuth signature using your keystore. You should see:

* `Authorization: OAuth oauth_consumer_key="...", oauth_signature_method="RSA-SHA256", oauth_signature="..."`

*** ** * ** ***

## Using the Collection {#using-the-collection}

### Retrieve Alerts (Pull API) {#retrieve-alerts-pull-api}

1. Click **Requests** → **Pull API** → **GET /alerts**
2. Modify query parameters as needed:
   * `alert_type` --- Filter by `CUSTOMERDISPUTE` or `CONFIRMEDFRAUD`
   * `from_date` --- Start date (YYYY-MM-DD)
   * `to_date` --- End date (YYYY-MM-DD)
   * `size` --- Number of results (1--1000)
3. Click **Send**
4. Review the **Response** tab for alert data

### Acknowledge Alerts {#acknowledge-alerts}

1. Click **Requests** → **Pull API** → **POST /alerts/acknowledges**
2. In the **Body** tab, modify the alert IDs to match alerts you retrieved:

   ```json
   {
     "acknowledgements": [
       {
         "alertId": "ALERT_ID_FROM_PREVIOUS_RESPONSE",
         "status": "SUCCESS"
       }
     ]
   }
   ```

3. Click **Send**
4. Verify the response shows success for each acknowledgement

### Submit Outcomes {#submit-outcomes}

1. Click **Requests** → **Outcome API** → **POST /outcomes**
2. In the **Body** tab, modify the alert ID and outcome code:

   ```json
   {
     "outcomes": [
       {
         "alertId": "ALERT_ID_FROM_ALERTS_RESPONSE",
         "alertType": "CUSTOMERDISPUTE",
         "outcomeCodes": [
           {
             "codeType": "INVESTIGATION_RESULT",
             "code": "RESOLVED"
           }
         ]
       }
     ]
   }
   ```

3. Click **Send**
4. Verify the response shows success

### Push Webhook Simulation (Testing Only) {#push-webhook-simulation-testing-only}

The collection includes a **Push Webhook** request that simulates an incoming webhook from Ethoca. This is useful for testing your webhook handler in isolation:

1. Click **Requests** → **Push API** → **POST /webhook (Simulation)**
2. Review the simulated webhook payload in the **Body** tab
3. Update the `POST` URL to your local webhook endpoint (for example, `http://localhost:8080/ethoca/webhook`)
4. Click **Send**
5. Verify your webhook handler processes the payload correctly

*** ** * ** ***

## Running Test Scripts {#running-test-scripts}

The collection includes automated test scripts that validate responses. To run them:

1. Select any request from the collection
2. Click the **Tests** tab to view the script
3. Click **Send** to run the request and tests
4. Check the **Test Results** tab to see pass/fail status

Common test validations:

* HTTP status code is 200
* Response contains expected fields
* No validation errors returned

*** ** * ** ***

## Troubleshooting {#troubleshooting}

**401 Unauthorized Error**

* Verify that `consumer_key`, `keystore_path`, and `keystore_password` are correct in your environment
* Confirm the keystore file exists at the specified path
* Check that you've selected the correct Environment in Postman

**Connection Refused**

* Confirm that `base_url` is correct for your environment (Sandbox vs. Production)
* Verify network connectivity to `sandbox.api.ethocaweb.com` or `api.ethocaweb.com`

**Empty Alert List**

* Ensure that test alerts have been submitted to Sandbox
* Verify the date range in your `GET /alerts` request covers the alert submission time

*** ** * ** ***

## Next Steps {#next-steps}

* Review [Quick Start Guide](https://static.developer.mastercard.com/content/ethoca-alerts-for-merchants/documentation/developer-tools/tutorials-and-guides/quick-start-guide.md) for integration setup
* See [Testing](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/testing/index.md) for comprehensive test scenarios
* Refer to [API Reference](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/api-reference/index.md) for endpoint specifications
* Check [Codes \& Formats](https://developer.mastercard.com/ethoca-alerts-for-merchants/documentation/developer-tools/code-and-formats/index.md) for error code reference