curl --request GET \
--url https://api.staging.payrails.io/dispute/disputes/alerts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.staging.payrails.io/dispute/disputes/alerts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.staging.payrails.io/dispute/disputes/alerts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.staging.payrails.io/dispute/disputes/alerts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.staging.payrails.io/dispute/disputes/alerts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.staging.payrails.io/dispute/disputes/alerts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.payrails.io/dispute/disputes/alerts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"links": {
"self": "<string>",
"prev": "<string>",
"next": "<string>",
"first": "<string>",
"last": "<string>"
},
"results": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"enrollmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalReference": "<string>",
"program": "Ethoca",
"amount": {
"value": "12.50",
"currency": "EUR"
},
"matchState": "matched",
"status": "Received",
"workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"providerCreatedAt": "2023-11-07T05:31:56Z",
"category": "PreChargeback",
"alertType": "<string>",
"cardBIN": "<string>",
"acquirerBIN": "<string>",
"acquirerCAID": "<string>",
"cardLast4": "<string>",
"network": "<string>",
"descriptor": "<string>",
"arn": "<string>",
"authCode": "<string>",
"transactionDate": "2023-11-07T05:31:56Z",
"expiresAt": "2023-11-07T05:31:56Z",
"paymentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"candidatePayments": [
{
"paymentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"reason": "<string>",
"outcome": "Resolved",
"displayStatus": "Processing",
"actionedVia": "<string>",
"actionedByUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"actionedAt": "2023-11-07T05:31:56Z",
"lastError": "<string>",
"ruleset": "<string>",
"disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.malformed",
"detail": "The request has malformed syntax",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.unauthorized",
"detail": "The request lacks necessary credentials to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
}
]
}{
"errors": [
{
"id": "e7db22b3-914e-4975-928e-9edfb0885bea",
"code": "request.forbidden",
"detail": "The request credentials lack the required permissions to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.not-found",
"detail": "The requested resource was not found",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.rate-limit",
"detail": "Too many requests",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
}
]
}Search & list Dispute Alerts
Search and list pre-chargeback dispute alerts in your workspace. Use the available filters to narrow results by status, match state, program, and date range.
curl --request GET \
--url https://api.staging.payrails.io/dispute/disputes/alerts \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.staging.payrails.io/dispute/disputes/alerts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.staging.payrails.io/dispute/disputes/alerts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.staging.payrails.io/dispute/disputes/alerts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.staging.payrails.io/dispute/disputes/alerts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.staging.payrails.io/dispute/disputes/alerts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.payrails.io/dispute/disputes/alerts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"links": {
"self": "<string>",
"prev": "<string>",
"next": "<string>",
"first": "<string>",
"last": "<string>"
},
"results": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"enrollmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"externalReference": "<string>",
"program": "Ethoca",
"amount": {
"value": "12.50",
"currency": "EUR"
},
"matchState": "matched",
"status": "Received",
"workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"providerCreatedAt": "2023-11-07T05:31:56Z",
"category": "PreChargeback",
"alertType": "<string>",
"cardBIN": "<string>",
"acquirerBIN": "<string>",
"acquirerCAID": "<string>",
"cardLast4": "<string>",
"network": "<string>",
"descriptor": "<string>",
"arn": "<string>",
"authCode": "<string>",
"transactionDate": "2023-11-07T05:31:56Z",
"expiresAt": "2023-11-07T05:31:56Z",
"paymentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"candidatePayments": [
{
"paymentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
],
"reason": "<string>",
"outcome": "Resolved",
"displayStatus": "Processing",
"actionedVia": "<string>",
"actionedByUserId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"actionedAt": "2023-11-07T05:31:56Z",
"lastError": "<string>",
"ruleset": "<string>",
"disputeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.malformed",
"detail": "The request has malformed syntax",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestmalformed"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.unauthorized",
"detail": "The request lacks necessary credentials to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestunauthorized"
}
]
}{
"errors": [
{
"id": "e7db22b3-914e-4975-928e-9edfb0885bea",
"code": "request.forbidden",
"detail": "The request credentials lack the required permissions to perform the specified action",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestforbidden"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.not-found",
"detail": "The requested resource was not found",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestnot-found"
}
]
}{
"errors": [
{
"id": "a24bc325-3929-4d9d-9c08-b3aa532685b7",
"code": "request.rate-limit",
"detail": "Too many requests",
"docUrl": "https://docs.payrails.com/docs/resources/error-codes#requestrate-limit"
}
]
}Authorizations
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.
Query Parameters
Filter for a list of alerts by ID.
Filter for a list of alerts by workspace ID.
Filter for a list of alerts by enrollment ID.
Filter for a list of alerts by status (e.g. Received, Resolved, Declined).
Filter for a list of alerts by one or more merchant-facing status buckets, comma-separated (e.g. filter[displayStatus]=Processing,ActionNeeded).
Filter for a list of alerts by match state (matched, unmatched, ambiguous, retrying).
Filter for a list of alerts by network program (Ethoca, CDRN, RDR, SAFE).
Filter for a list of alerts by matched payment ID.
Filter for a list of alerts by linked dispute ID.
Filter for a list of alerts by Acquirer Reference Number.
Filter for a list of alerts by creation date. Accepts ISO 8601 date-time values or range expressions (e.g. [2024-01-01T00:00:00Z,2024-12-31T23:59:59Z)).
Filter for a list of alerts by provider creation date. Accepts ISO 8601 date-time values or range expressions.
Response
Success.
Hide child attributes
Hide child attributes
ID of the enrollment that produced this alert.
The provider's identifier for this alert.
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.
Ethoca, CDRN, RDR, SAFE, TC40, TC15, Discover, AMEX, JCB, Unknown How the alert maps to a Payrails payment.
matched, unmatched, ambiguous, retrying Lifecycle state of the alert.
Received, Resolved, Declined, WillExpire, Expired, ActionFailed, RefundInitiated The workspace of the matched payment; absent until the alert is matched.
When the provider created the alert.
Broad category derived from program. PreChargeback covers actionable programmes (Ethoca, CDRN, RDR). FraudReport covers reporting-only programmes (SAFE, TC40, TC15).
PreChargeback, FraudReport 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.
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.
The acquirer's card acceptor ID for an RDR alert, paired with acquirerBIN. Populated for RDR only; null for every other program.
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.
The merchant descriptor carried on the alert.
Acquirer Reference Number used to match the alert to a payment.
When the alert's action window closes, derived from the provider's near-expiry notification. Null until that notification is received.
The matched Payrails payment, when the alert resolved to a single payment.
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.
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.
Resolved, AlreadyRefunded, AlreadyChargeback, Ineligible, MIDLost, NotMyDescriptor, EscalateChargeback, TDS, UnmatchedCannotFindTransaction 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].
Processing, ActionNeeded, Ignored, Refunded, Expired, Unrecognized, RefundInitiated How the alert was actioned (e.g. portal).
The user who actioned the alert, when actioned by a portal user.
The dispute this alert is linked to, when a chargeback followed.