Skip to main content
GET
Get Dispute Alert by ID

Authorizations

Authorization
string
header
required

You can use an OAuth2 JWT bearer token in the Authorization header of your API requests for supported endpoints: Authorization: Bearer <YOUR_JWT_HERE>. These tokens are valid for 10 minutes and can be requested via the access token endpoint endpoint.

Path Parameters

alertId
string<uuid>
required

Identifier of the resource in Payrails.

Response

Alert found.

id
string<uuid>
required
createdAt
string<date-time>
required
updatedAt
string<date-time>
required
enrollmentId
string<uuid>
required

ID of the enrollment that produced this alert.

externalReference
string
required

The provider's identifier for this alert.

program
enum<string>
required

The network program that issued the alert, taken from the provider webhook. Ethoca, CDRN, and RDR are actionable pre-chargeback programmes (the merchant can resolve or decline the alert). SAFE, TC40, and TC15 are fraud-reporting feeds — they are stored for reporting and analytics but cannot be actioned (attempting to action them returns 409). Unknown is a forward-compatible sentinel for a program Payrails does not yet have a canonical value for.

Available options:
Ethoca,
CDRN,
RDR,
SAFE,
TC40,
TC15,
Discover,
AMEX,
JCB,
Unknown
amount
object
required
matchState
enum<string>
required

How the alert maps to a Payrails payment.

Available options:
matched,
unmatched,
ambiguous,
retrying
status
enum<string>
required

Lifecycle state of the alert.

Available options:
Received,
Resolved,
Declined,
WillExpire,
Expired,
ActionFailed,
RefundInitiated
workspaceId
string<uuid> | null

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

providerCreatedAt
string<date-time> | null

When the provider created the alert.

category
enum<string>

Broad category derived from program. PreChargeback covers actionable programmes (Ethoca, CDRN, RDR). FraudReport covers reporting-only programmes (SAFE, TC40, TC15).

Available options:
PreChargeback,
FraudReport
alertType
string | null

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.

cardBIN
string | null
acquirerBIN
string | null

The acquiring BIN an RDR alert was routed on, taken verbatim from the provider webhook. Distinct from cardBIN, which is the issuer BIN derived from the cardholder PAN. Populated for RDR only; null for every other program.

acquirerCAID
string | null

The acquirer's card acceptor ID for an RDR alert, paired with acquirerBIN. Populated for RDR only; null for every other program.

cardLast4
string | null
network
string | null

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.

descriptor
string | null

The merchant descriptor carried on the alert.

arn
string | null

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

authCode
string | null
transactionDate
string<date-time> | null
expiresAt
string<date-time> | null

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

paymentId
string<uuid> | null

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

candidatePayments
object[] | null

The distinct payments the matcher found when it declared the alert ambiguous. Present only while matchState is ambiguous; pick one and submit it to the manual match endpoint to resolve the alert.

reason
string | null
outcome
enum<string> | null

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.

Available options:
Resolved,
AlreadyRefunded,
AlreadyChargeback,
Ineligible,
MIDLost,
NotMyDescriptor,
EscalateChargeback,
TDS,
UnmatchedCannotFindTransaction
displayStatus
enum<string>
read-only

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].

Available options:
Processing,
ActionNeeded,
Ignored,
Refunded,
Expired,
Unrecognized,
RefundInitiated
actionedVia
string | null

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

actionedByUserId
string<uuid> | null

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

actionedAt
string<date-time> | null
lastError
string | null
ruleset
string | null
disputeId
string<uuid> | null

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

subscriptionCancellation
object

Outcome of an automated billing-subscription cancellation for this alert. Present only when a cancellation was attempted; the key is omitted entirely — never sent as null — when no attempt was made, for example when the merchant has no billing provider configured or the feature is off.

Last modified on October 9, 2026