Dispute alert notifications

A dispute alert is an early warning from a prevention programme (Ethoca, CDRN, RDR, and similar) that a transaction is about to become a chargeback. Acting on the alert in time, usually with a refund, can stop the chargeback from being filed. Dispute alert notifications tell you when an alert is received, when it is about to expire, and how it ends. They are separate from dispute notifications, which cover chargebacks that have already been filed.

How you receive them

Alert notifications are sent by the notify step of your dispute-management workflow. Three things must be in place:

Dispute alert notifications are enabled for your merchant account. They are off by default. Ask your Payrails contact to enable them.
Your dispute-management workflow has an event trigger for each alert event you want, followed by a notify step with event type executionActionCompleted.
A webhook endpoint is registered for the workspace, with the dispute-management workflow and the executionActionCompleted event enabled on it. Without one, the notify step runs but nothing is delivered.

The event triggers are:

Trigger event	Sent when
`AlertReceived`	A new alert arrives. Sent once per alert.
`AlertExpiring`	The provider warns that the alert is close to its deadline. Sent once per alert.
`AlertExpired`	The action window closed without a decision. Sent once per alert.
`AlertResolved`	The alert was refunded, or the network already refunded it.
`AlertDeclined`	The alert was declined, so a chargeback may follow. This includes alerts Payrails could not match to a transaction.
`AlertUpdated`	The alert changed in a way that is not a terminal outcome: it was matched to a payment, or a refund started, failed, or retried.

An alert can produce more than one event. For example, an alert created already resolved (RDR) sends AlertReceived followed by AlertResolved.

The notification

The important fields in the dispute alert notification include:

event is executionActionCompleted and eventTrigger is external
action is empty. Alert notifications do not map to a payment action like dispute, so do not filter on it
execution.workflowCode is dispute-management and execution.merchantReference is dispute-alert- followed by the alert ID
there’s an alert block in the paymentComposition object
- alert.id is the Payrails alert ID. It stays the same across all events for the alert
- alert.paymentId is the Payrails payment the alert was matched to. Absent while the alert is unmatched
- alert.program is the alert programme, for example Ethoca, CDRN, RDR, SAFE, TC40
- alert.amount is the alerted amount
- alert.descriptor and alert.arn identify the transaction on the card statement and the acquirer side
- alert.cardBin, alert.cardLast4 and alert.network describe the card
- alert.transactionDate is when the original transaction took place
- alert.status is a Payrails alert status, see below
- alert.outcome is set once the alert has reached an outcome
- alert.occurredAt is when the alert last changed. Use it to order events

alert.status can be one of the following:

alert.status	Description
`ActionNeeded`	The alert is waiting for a decision. Refund it before the deadline.
`Processing`	Payrails is still trying to match the alert to a payment. No action needed yet.
`RefundInitiated`	A refund for the alert was started and has not settled yet.
`Refunded`	The alert was resolved by a refund.
`Ignored`	The alert was declined. A chargeback may follow.
`Unrecognized`	Payrails could not find the transaction behind the alert.
`Expired`	Nobody acted in the grace period.

alert.outcome can be one of the following. It is omitted until an outcome exists.

alert.outcome	Description
`Resolved`	The transaction was refunded.
`AlreadyRefunded`	The transaction was already refunded before the alert arrived.
`AlreadyChargeback`	A chargeback was already raised before the alert arrived.
`Ineligible`	The alert cannot be acted on, for example because it is out of window.
`MIDLost`	The merchant ID was lost or changed since the transaction.
`NotMyDescriptor`	The descriptor does not belong to you.
`EscalateChargeback`	The refund was declined, so the chargeback proceeds.
`TDS`	The transaction was 3D Secure authenticated and is protected.
`UnmatchedCannotFindTransaction`	Payrails could not match the alert to a payment.

Currently supported alert providers are: Chargeblast (Ethoca, CDRN, RDR, SAFE, TC40 programmes).

SAFE (Mastercard) and TC40 (Visa) are fraud-reporting feeds. They are reported to you but no refund action is available.

Delivery notes

Duplicates are possible. AlertReceived, AlertExpiring and AlertExpired are sent once per alert. AlertResolved, AlertDeclined and AlertUpdated can be sent again on a retry. Treat alert.id together with alert.status and alert.occurredAt as your idempotency key.
Events can arrive out of order. Use alert.occurredAt to keep the latest state and ignore older ones.
Unmatched alerts. An alert that is not yet matched to a payment has no alert.paymentId. It is delivered only if your provider configuration is linked to a single workspace. Otherwise the notification is skipped. When the alert is later matched, AlertReceived is sent late if it was skipped, followed by AlertUpdated.
Delivery does not block processing. A failed delivery never blocks the alert from being processed. To read the current state of an alert, call the List dispute alerts endpoint.

A notification example: Fields that are not relevant to the alert are omitted in this example. execution.meta also carries amount, and paymentId when the alert was already matched when the execution started.

Dispute alert notification

{
  "event": "executionActionCompleted",
  "time": "2026-10-12T10:15:02Z",
  "workspaceId": "22222222-aaaa-4bbb-8ccc-333333333333",
  "eventTrigger": "external",
  "details": {
    "action": "",
    "actionId": "11111111-2e6e-5499-9bba-8795e382da46",
    "success": true,
    "execution": {
      "workflowCode": "dispute-management",
      "id": "6f1d3c2a-8b4e-4f0a-9c55-2d7e1a9b0c11",
      "merchantReference": "dispute-alert-6f1d3c2a-8b4e-4f0a-9c55-2d7e1a9b0c11",
      "holderReference": "",
      "meta": {
        "source": "alert",
        "alertId": "6f1d3c2a-8b4e-4f0a-9c55-2d7e1a9b0c11"
      }
    },
    "paymentComposition": [
      {
        "alert": {
          "id": "6f1d3c2a-8b4e-4f0a-9c55-2d7e1a9b0c11",
          "paymentId": "payment_111122223333",
          "program": "Ethoca",
          "descriptor": "PAYRAILS*EXAMPLE",
          "arn": "74123456789012345678901",
          "amount": {
            "currency": "USD",
            "value": "10.00"
          },
          "cardBin": "411111",
          "cardLast4": "1111",
          "network": "visa",
          "transactionDate": "2026-10-01T09:30:00Z",
          "status": "ActionNeeded",
          "occurredAt": "2026-10-12T10:15:00Z"
        }
      }
    ]
  }
}

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Dispute alert notifications

How you receive them

The notification

Delivery notes

​How you receive them

​The notification

​Delivery notes

How you receive them

The notification

Delivery notes