PApayrails
Disputes

Get Dispute Alert by ID

Retrieve a single pre-chargeback dispute alert by its ID.

get/dispute/disputes/alerts/{alertId}

Request

Path parameters

alertIdstring uuid required

Identifier of the resource in Payrails.

Response

Alert found.

idstring uuid required
createdAtstring date-time required
updatedAtstring date-time required
workspaceIdstring uuid nullable

The workspace of the matched payment; absent until the alert is matched.

enrollmentIdstring uuid required

ID of the enrollment that produced this alert.

externalReferencestring required

The provider's identifier for this alert.

providerCreatedAtstring date-time nullable

When the provider created the alert.

program'Ethoca' | 'CDRN' | 'RDR' | 'SAFE' | 'TC40' | 'Discover' | 'AMEX' | 'JCB' | 'Unknown' required

The network program that issued the alert. Unknown is a forward-compatible sentinel for a program Payrails does not yet have a canonical value for.

alertTypestring nullable

Provider-specific alert type. Open-ended (not a fixed enum); Chargeblast documents FRAUD and DISPUTE as known values but does not guarantee an exhaustive list.

cardBINstring nullable
cardLast4string nullable
networkstring nullable

The card network, normalized to the canonical Payrails value (commondto.CardNetwork — e.g. visa, mastercard, amex, discover, jcb), matching the payment instrument's network. Null when the provider's brand could not be classified.

descriptorstring nullable

The merchant descriptor carried on the alert.

arnstring nullable

Acquirer Reference Number used to match the alert to a payment.

authCodestring nullable
transactionDatestring date-time nullable
expiresAtstring date-time nullable

When the alert's action window closes, derived from the provider's near-expiry notification. Null until that notification is received.

paymentIdstring uuid nullable

The matched Payrails payment, when the alert resolved to a single payment.

matchState'matched' | 'unmatched' | 'ambiguous' | 'retrying' required

How the alert maps to a Payrails payment.

status'Received' | 'Resolved' | 'Declined' | 'WillExpire' | 'Expired' | 'ActionFailed' required

Lifecycle state of the alert.

reasonstring nullable
outcome'Resolved' | 'AlreadyRefunded' | 'AlreadyChargeback' | 'Ineligible' | 'MIDLost' | 'NotMyDescriptor' | 'EscalateChargeback' | 'TDS' | 'UnmatchedCannotFindTransaction' nullable

The specific outcome the merchant selected when actioning the alert (the result from the action request). Persisted alongside the binary status. Null until the alert is successfully actioned.

displayStatus'Processing' | 'ActionNeeded' | 'Ignored' | 'Refunded' | 'Expired' | 'Unrecognized'

Merchant-facing status bucket, derived from status, matchState and outcome (computed server-side, not stored). Also accepted as a multi-select filter via filter[displayStatus].

actionedViastring nullable

How the alert was actioned (e.g. portal).

actionedByUserIdstring uuid nullable

The user who actioned the alert, when actioned by a portal user.

actionedAtstring date-time nullable
lastErrorstring nullable
rulesetstring nullable
disputeIdstring uuid nullable

The dispute this alert is linked to, when a chargeback followed.

Example response

{
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.