# Merchant Threat Intelligence
source: https://developer.mastercard.com/mastercard-threat-intelligence/documentation/use-cases/merchant-threat-intelligence/index.md

## Overview {#overview}

This document provides practical usage scenarios for the Merchant Threat Intelligence API, illustrating how Issuers, Acquirers, and other ecosystem participants can leverage threat intelligence to assess merchant risk, support investigations, and make informed operational decisions.

This use case describes the business context, objective, participating actors, preconditions, and expected outcomes, followed by a walk through that includes the process flow, sequence diagram, API endpoints used, and representative request and response examples. Together, they demonstrate how Merchant Threat Intelligence can be integrated into existing workflows to enhance risk visibility, investigation efficiency, and decision-making.

## Assess Merchant Domain Risk {#assess-merchant-domain-risk}

### Context {#context}

Merchant Domain Risk Assessment

An Acquirer receives a request to onboard a new merchant or review an existing merchant exhibiting unusual transaction activity. To support risk assessment, the Acquirer wants to determine whether the merchant's digital presence has been associated with known threats, suspicious infrastructure, or other indicators that may warrant additional investigation before onboarding approval or continued acceptance.

### Goal {#goal}

Retrieve payment-focused risk intelligence for one or more merchant domains.

### Main actors {#main-actors}

The analyst, your application, and the Mastercard Threat Intelligence API.

### Preconditions {#preconditions}

* Merchant identifier, merchant domain, or merchant website is available.
* User has access to Mastercard Threat Intelligence APIs.
* Necessary API credentials and OAuth access tokens have been obtained.

### Desired outcome {#desired-outcome}

* Merchant threat intelligence is successfully retrieved.
* Risk indicators associated with the merchant are identified and reviewed.
* Analysts gain additional context regarding the merchant's potential exposure to threat activity.
* The onboarding, monitoring, or investigation process is informed by intelligence-driven insights.

## Steps {#steps}

1. Collect the merchant domains to evaluate. The API endpoint supports bulk inquiry for merchants up to 50 per request.
2. Send a search request with a `reason` and the list of `domains`.
3. Read the risk categories, signals, and status in each report.
4. Use the risk counts to decide the next action.

### Sequence {#sequence}

Diagram mti-merchant-domain

## Endpoint {#endpoint}


API Reference: `POST /exposures/domains`

### Key parameters {#key-parameters}

* `reason` (required): the reason for the inquiry. Allowed values are `MERCHANT_UNDERWRITING_CONCERNS`, `COLLUSIVE_MERCHANT`, and `SCAM_MERCHANT`.
* `domains` (required): one to 50 merchant domains to evaluate.

## Example request {#example-request}

```json
{
  "reason": "MERCHANT_UNDERWRITING_CONCERNS",
  "domains": ["suspicious-shop.com"]
}
```

## Example response {#example-response}

```json
{
  "reports": [
    {
      "domain": "suspicious-shop.com",
      "firstSeen": "2019-03-25T05:09:35Z",
      "domainAgeRiskCategory": "Lower risk - observed for a while",
      "risksFound": 5,
      "totalRisks": 9,
      "categories": [
        {
          "categoryName": "Payment Fraud",
          "severityColor": "RED",
          "risksFound": 2,
          "totalRisks": 2,
          "risks": [
            { "rule": "Merchant Identified in Previous Card Data Breach", "timestamp": "2023-03-17T16:32:35Z" }
          ]
        }
      ],
      "status": "PASSED"
    }
  ]
}
```

## Error Handling and Scenarios {#error-handling-and-scenarios}

Every endpoint uses the same error model. An error response includes `source`, `error`, `recoverable`, and `error_description`. The `recoverable` field indicates whether retrying could change the outcome.

The most common scenarios across all use cases are:

* `400 Bad Request`: a field fails validation, for example an out-of-range `limit` or an invalid `reason`. Correct the request and send it again.
* `403 Forbidden`: your project lacks access to the requested feature or data scope. Confirm your product enrollment, credentials, environment, and entitlements.

For detailed error questions and troubleshooting, see the [Codes and Formats](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/code-and-formats/index.md) page. For the full list of status codes and error fields, see the error models in the [API Reference](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-reference/index.md).