> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastercard Ethoca Alerts

> Auto-refund Mastercard Ethoca pre-dispute alerts before they become chargebacks, and cancel the customer's subscriptions at your account.

Ethoca alerts are pre-dispute notifications. When an issuer confirms fraud on a charge, or a cardholder disputes it with their bank, Ethoca notifies PayNext before the dispute becomes a chargeback. PayNext refunds the payment and reports the outcome back to the network, so the case closes without a chargeback, a dispute fee, or an entry against your chargeback ratio.

Ethoca is Mastercard's pre-dispute network. It carries alerts for both Mastercard and Visa, with primary coverage on Mastercard. Each alert is recorded on the payment as `fraud_prevention.mastercard_ethoca_alert`.

## Alert types

The kind of alert that landed on the payment is recorded as `mastercard_ethoca_alert.alert_type`.

| Value                   | What it means                                                                                                                     |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `issuer_alert`          | Confirmed fraud, reported by the issuer. The issuing bank has established that the charge was not made by the genuine cardholder. |
| `customerdispute_alert` | The cardholder disputed the charge with their bank. A chargeback follows unless the case is resolved first.                       |

Both types are actionable, and PayNext treats them the same way: refund in full, cancel the customer's subscriptions, report the outcome. No other value appears in `alert_type`.

## How Ethoca alerts work

<Steps>
  <Step title="Ethoca sends the alert">
    The issuer confirms fraud, or the cardholder disputes the charge. Ethoca notifies PayNext.
  </Step>

  <Step title="PayNext matches the alert to your payment">
    PayNext matches the alert to your payment automatically, using the transaction identifiers the network provides. In the rare event an alert can't be matched, nothing changes on your payments.
  </Step>

  <Step title="PayNext refunds and cancels">
    The disputed payment is refunded in full, and the customer's active subscriptions at your account are cancelled immediately.
  </Step>

  <Step title="PayNext reports the outcome to Ethoca">
    Ethoca expects a response within 24 hours. PayNext reports the outcome once the refund succeeds. The response is write-once—it cannot be amended afterwards.
  </Step>
</Steps>

When PayNext resolves an alert, it refunds the disputed payment in full—PayNext never issues a partial refund. To prevent a repeat dispute from the same cardholder, PayNext may also refund the customer's later payments at your account, meaning those taken after the disputed one. Earlier payments are left alone. All refunds appear on the payment with a `refund_reason` of `fraud_prevention`.

Expect more than one alert on the same payment: the issuer and the network can both report the same charge. The payment always shows the most recent alert.

## Subscription handling

When an Ethoca alert lands on a payment that belongs to an active subscription, PayNext cancels the subscription immediately. Both alert types are strong signals that the cardholder no longer wants the charge to recur. The subscription `status` becomes `cancelled`.

All of the customer's active subscriptions at your account are acted on. Subscriptions the same customer holds at other merchants are not affected. Track changes via the `subscription_v2.cancelled` webhook.

<Note>
  Both actions are attributed automatically as `fraud_prevention`: the refunded payment's `refund_reason` and the cancelled subscription's [`cancellation_details.reason`](/guides/platform/subscriptions#cancellation-details) are set to `fraud_prevention`, with `trigger_payment_id` pointing at the disputed payment—so you can distinguish alert-driven activity from `merchant_initiated` actions.
</Note>

## Set up

<Steps>
  <Step title="Contact PayNext support">
    Request Ethoca enrollment and list the statement descriptors to cover.
  </Step>

  <Step title="PayNext enrolls your descriptor with Ethoca">
    Ethoca alerts enroll by statement descriptor, not by CAID. PayNext handles the registration end-to-end.
  </Step>

  <Step title="Done">
    No code changes required. Alerts appear on the `fraud_prevention.mastercard_ethoca_alert` sub-object of every affected payment.
  </Step>
</Steps>

## `mastercard_ethoca_alert` payload

Written when Ethoca raises an alert on the payment.

```json theme={"system"}
{
  "mastercard_ethoca_alert": {
    "alert_id": "BPHND524TLN0QQZA1O1GBW18Q",
    "alert_type": "customerdispute_alert",
    "updated_at": "2026-04-23T12:45:51Z",
    "source": "ethoca",
    "reason": {
      "reason_code": "4837"
    }
  }
}
```

| Field        | Type              | Description                                                                                                                                                                |
| :----------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `alert_id`   | string            | Ethoca's identifier for the alert. An opaque string, **not a UUID**—don't parse it or assume a format.                                                                     |
| `alert_type` | string            | Either `issuer_alert` or `customerdispute_alert`.                                                                                                                          |
| `updated_at` | string (ISO-8601) | When the network raised the alert, UTC with `Z` suffix.                                                                                                                    |
| `source`     | string, optional  | Origin of the alert, passed through as received. Omitted when the network doesn't supply it.                                                                               |
| `reason`     | object, optional  | Present only when the network supplies a chargeback reason. Contains `reason_code`—the raw scheme code as a string, passed through verbatim. Optional on both alert types. |

## Read the payload

| Payload state                          | Meaning                                                        |
| :------------------------------------- | :------------------------------------------------------------- |
| `mastercard_ethoca_alert` absent       | No Ethoca alert has landed on this payment                     |
| `alert_type = "issuer_alert"`          | The issuer confirmed fraud on this charge                      |
| `alert_type = "customerdispute_alert"` | The cardholder disputed this charge with their bank            |
| `reason` present                       | The network supplied a chargeback reason code for the alert    |
| `reason` absent                        | The network supplied no reason code—expected, and not an error |

<Note>
  Once `mastercard_ethoca_alert` is written, it is never cleared. A later alert on the same payment replaces the whole sub-object—last-write-wins.
</Note>

## Where you see results

An alert is recorded on the payment it matched, so the payment is where you look for it—there's no separate alerts screen.

To check a single payment, open **Dashboard → Payments**, select the payment, and read its timeline: an entry reads **Mastercard Ethoca Alert (Issuer alert)**, next to the refund and the subscription cancellation the alert triggered. To find every affected payment, filter the Payments list by Ethoca alert **Type** or **Reason Code**. In your own systems, read `fraud_prevention.mastercard_ethoca_alert` from the payment.

| Surface                   | What you get                                                                                                                                          |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payment timeline          | **Dashboard → Payments → \[payment]**—an entry reading **Mastercard Ethoca Alert (Issuer alert)**, plus the refund and cancellation entries.          |
| Payment payload           | `fraud_prevention.mastercard_ethoca_alert` on the payment, carrying the alert type and reason code. Read it from the API, or receive it on a webhook. |
| Payment filters           | **Dashboard → Payments → More filters**—filter by Ethoca alert **Type** and **Reason Code**.                                                          |
| Analytics filters         | The same filters narrow every chart and metric on the analytics dashboard.                                                                            |
| Analytics chart           | **Risk** tab—**Ethoca alerts**, broken down by type, as a share of settled card payments. The chart labels `issuer_alert` as **Confirmed fraud**.     |
| Refunds and cancellations | The refund reason and the subscription cancellation reason both read **Fraud prevention**.                                                            |

<Note>
  The same alert type is worded differently across surfaces: payment filters and the timeline show **Issuer alert**, while the analytics chart shows **Confirmed fraud**. Both refer to `issuer_alert`.
</Note>

## Related products

Ethoca's primary coverage is the Mastercard network. [Visa CDRN Alerts](/guides/fraud-prevention/visa-cdrn-alerts) is the Visa-network counterpart—enroll in both for full pre-dispute coverage across networks.

## Webhook events

Updates to `mastercard_ethoca_alert` are delivered on the `payment_v2.updated` event. See [Webhook event types](/webhooks/introduction/event-types) and the [Payment webhook object](/webhooks/objects/payment/payment) for the full schema.