curl --request GET \
--url https://api.staging.payrails.io/dispute/disputes \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.staging.payrails.io/dispute/disputes"
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', 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",
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"
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")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.payrails.io/dispute/disputes")
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": "https://api.staging.payrails.io/dispute/disputes?page[after]=qf7pnbyfrr&page[size]=2",
"prev": "https://api.staging.payrails.io/dispute/disputes?page[before]=hbe66nh8i8&page[size]=2",
"next": "https://api.staging.payrails.io/dispute/disputes?page[after]=xk2h55zsy5&page[size]=2",
"first": "https://api.staging.payrails.io/dispute/disputes?page[size]=2",
"last": "https://api.staging.payrails.io/dispute/disputes?page[before]=9wkueqcavq&page[size]=2"
},
"results": [
{
"id": "56efbab8-53fa-5a14-9780-5c6d1aa80619",
"createdAt": "2026-01-13T16:20:05.740802Z",
"updatedAt": "2026-01-13T16:20:05.740802Z",
"workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"providerReference": "P6KQKF9S8D77Z5V5",
"providerCreatedAt": "2026-01-13T16:20:04.102Z",
"payment": {
"id": "9f3700b5-8cba-41e4-b36a-89e021b5bb02",
"createdAt": "2026-01-13T16:20:00.635896Z",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerName": "adyen",
"providerReference": "XCCMR76F3RJMQJV5",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"workspaceId": "00000000-0000-0000-0000-000000000000",
"holderId": "dbfe3474-71ca-4cdd-9fcb-d48b46a923df",
"amount": {
"value": "22.65",
"currency": "EUR"
},
"status": "Captured",
"instrumentId": "b8eaa596-7660-4e18-8d42-8060671e0cd7",
"meta": {
"clientContext": {
"ipAddress": "217.110.239.132",
"origin": "https://example.com",
"osType": "ios"
},
"customer": {
"country": {
"code": "DE"
},
"lastName": "Doe",
"name": "John",
"reference": "Holder-c5026204-ef0f-4d47-80b6-cd3b445210d6"
},
"order": {
"reference": "57e06696-73f2-4c99-9dc3-d1619a4fb9db"
},
"risk": {
"allowNative3DS": false
}
},
"merchantReference": "Merchant-cf0c5c0c-ce6b-413a-b4df-b95a30288327",
"paymentMethodType": "card",
"holderReference": "Holder-c5026204-ef0f-4d47-80b6-cd3b445210d6"
},
"paymentId": "9f3700b5-8cba-41e4-b36a-89e021b5bb02",
"amount": {
"value": "22.65",
"currency": "EUR"
},
"applicableDefenseReasons": [
{
"providerReasonCode": "CreditOrCancellationPolicyProperlyDisclosed",
"evidenceTypes": [
{
"providerTypeCode": "DisclosureAtPointOfInteraction",
"required": true
}
]
}
],
"reason": "Services not provided/Merchandise not received]",
"stage": "Chargeback",
"chargebackStatus": "Incoming",
"defenseStatus": "Undefended"
},
{
"id": "1746359e-5674-5bc2-94ea-2efa5d415753",
"createdAt": "2026-01-13T16:20:11.699603Z",
"updatedAt": "2026-01-13T21:26:55.757444Z",
"workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"providerReference": "W7LQKF9S8D77Z5V5",
"providerCreatedAt": "2026-01-13T16:20:10.283Z",
"payment": {
"id": "c585e119-8584-4136-b4f0-f4f08f00619f",
"createdAt": "2026-01-13T16:20:06.660318Z",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerName": "adyen",
"providerReference": "DNMZS76F3RJMQJV5",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"workspaceId": "00000000-0000-0000-0000-000000000000",
"holderId": "260fdd51-fc42-48b6-aca1-4eb573fa120b",
"amount": {
"value": "37.54",
"currency": "EUR"
},
"status": "Captured",
"instrumentId": "f1ebd3bb-d813-4149-867e-6634b57fd417",
"meta": {
"clientContext": {
"ipAddress": "217.110.239.132",
"origin": "https://example.com",
"osType": "ios"
},
"customer": {
"country": {
"code": "DE"
},
"lastName": "Doe",
"name": "John",
"reference": "Holder-537d8c47-36c3-4f29-88f7-cfc2f5e6ca65"
},
"order": {
"reference": "547eb508-c5b6-4eb4-8439-57bbba0c143d"
},
"risk": {
"allowNative3DS": false
}
},
"merchantReference": "Merchant-5f65c13d-5858-43f3-aa0d-5fb6218ac9fc",
"paymentMethodType": "card",
"holderReference": "Holder-537d8c47-36c3-4f29-88f7-cfc2f5e6ca65"
},
"paymentId": "c585e119-8584-4136-b4f0-f4f08f00619f",
"amount": {
"value": "37.54",
"currency": "EUR"
},
"reason": "Canceled recurring transaction",
"stage": "Chargeback",
"chargebackStatus": "Incoming",
"defenseStatus": "UnderReview"
}
]
}{
"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 Disputes
Search and list disputes in your workspace. Use the available filters to narrow results by status, payment, provider, date range, and more.
curl --request GET \
--url https://api.staging.payrails.io/dispute/disputes \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.staging.payrails.io/dispute/disputes"
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', 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",
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"
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")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.staging.payrails.io/dispute/disputes")
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": "https://api.staging.payrails.io/dispute/disputes?page[after]=qf7pnbyfrr&page[size]=2",
"prev": "https://api.staging.payrails.io/dispute/disputes?page[before]=hbe66nh8i8&page[size]=2",
"next": "https://api.staging.payrails.io/dispute/disputes?page[after]=xk2h55zsy5&page[size]=2",
"first": "https://api.staging.payrails.io/dispute/disputes?page[size]=2",
"last": "https://api.staging.payrails.io/dispute/disputes?page[before]=9wkueqcavq&page[size]=2"
},
"results": [
{
"id": "56efbab8-53fa-5a14-9780-5c6d1aa80619",
"createdAt": "2026-01-13T16:20:05.740802Z",
"updatedAt": "2026-01-13T16:20:05.740802Z",
"workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"providerReference": "P6KQKF9S8D77Z5V5",
"providerCreatedAt": "2026-01-13T16:20:04.102Z",
"payment": {
"id": "9f3700b5-8cba-41e4-b36a-89e021b5bb02",
"createdAt": "2026-01-13T16:20:00.635896Z",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerName": "adyen",
"providerReference": "XCCMR76F3RJMQJV5",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"workspaceId": "00000000-0000-0000-0000-000000000000",
"holderId": "dbfe3474-71ca-4cdd-9fcb-d48b46a923df",
"amount": {
"value": "22.65",
"currency": "EUR"
},
"status": "Captured",
"instrumentId": "b8eaa596-7660-4e18-8d42-8060671e0cd7",
"meta": {
"clientContext": {
"ipAddress": "217.110.239.132",
"origin": "https://example.com",
"osType": "ios"
},
"customer": {
"country": {
"code": "DE"
},
"lastName": "Doe",
"name": "John",
"reference": "Holder-c5026204-ef0f-4d47-80b6-cd3b445210d6"
},
"order": {
"reference": "57e06696-73f2-4c99-9dc3-d1619a4fb9db"
},
"risk": {
"allowNative3DS": false
}
},
"merchantReference": "Merchant-cf0c5c0c-ce6b-413a-b4df-b95a30288327",
"paymentMethodType": "card",
"holderReference": "Holder-c5026204-ef0f-4d47-80b6-cd3b445210d6"
},
"paymentId": "9f3700b5-8cba-41e4-b36a-89e021b5bb02",
"amount": {
"value": "22.65",
"currency": "EUR"
},
"applicableDefenseReasons": [
{
"providerReasonCode": "CreditOrCancellationPolicyProperlyDisclosed",
"evidenceTypes": [
{
"providerTypeCode": "DisclosureAtPointOfInteraction",
"required": true
}
]
}
],
"reason": "Services not provided/Merchandise not received]",
"stage": "Chargeback",
"chargebackStatus": "Incoming",
"defenseStatus": "Undefended"
},
{
"id": "1746359e-5674-5bc2-94ea-2efa5d415753",
"createdAt": "2026-01-13T16:20:11.699603Z",
"updatedAt": "2026-01-13T21:26:55.757444Z",
"workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"providerReference": "W7LQKF9S8D77Z5V5",
"providerCreatedAt": "2026-01-13T16:20:10.283Z",
"payment": {
"id": "c585e119-8584-4136-b4f0-f4f08f00619f",
"createdAt": "2026-01-13T16:20:06.660318Z",
"providerId": "c1e7b01d-da66-4b1c-be33-9ac3bf6e9ae7",
"providerName": "adyen",
"providerReference": "DNMZS76F3RJMQJV5",
"providerConfigId": "5eb08624-ecce-4cbc-9a8a-61d484172815",
"workspaceId": "00000000-0000-0000-0000-000000000000",
"holderId": "260fdd51-fc42-48b6-aca1-4eb573fa120b",
"amount": {
"value": "37.54",
"currency": "EUR"
},
"status": "Captured",
"instrumentId": "f1ebd3bb-d813-4149-867e-6634b57fd417",
"meta": {
"clientContext": {
"ipAddress": "217.110.239.132",
"origin": "https://example.com",
"osType": "ios"
},
"customer": {
"country": {
"code": "DE"
},
"lastName": "Doe",
"name": "John",
"reference": "Holder-537d8c47-36c3-4f29-88f7-cfc2f5e6ca65"
},
"order": {
"reference": "547eb508-c5b6-4eb4-8439-57bbba0c143d"
},
"risk": {
"allowNative3DS": false
}
},
"merchantReference": "Merchant-5f65c13d-5858-43f3-aa0d-5fb6218ac9fc",
"paymentMethodType": "card",
"holderReference": "Holder-537d8c47-36c3-4f29-88f7-cfc2f5e6ca65"
},
"paymentId": "c585e119-8584-4136-b4f0-f4f08f00619f",
"amount": {
"value": "37.54",
"currency": "EUR"
},
"reason": "Canceled recurring transaction",
"stage": "Chargeback",
"chargebackStatus": "Incoming",
"defenseStatus": "UnderReview"
}
]
}{
"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 disputes by ID.
Filter for a list of disputes by provider ID.
Filter for a list of disputes by provider config ID.
Filter for a list of disputes by provider reference.
Filter for a list of disputes by payment ID.
Filter for a list of disputes by payment provider reference.
Filter for a list of disputes by holder reference.
Filter for a list of disputes by customer email.
Filter for a list of disputes by stage.
Filter for a list of disputes by defense status.
Filter for a list of disputes by chargeback status.
Filter for a list of disputes by the channel the customer used to raise them.
Filter for a list of disputes by assigned to user email.
Filter for a list of disputes by defense period expiration date.
Filter for a list of disputes by reason.
Filter for a list of disputes by reason code.
Filter for a list of disputes by provider created at 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 disputes by merchant reference.
Filter for a list of disputes by execution ID.
Filter disputes by attached tag slugs. Accepts a comma-separated list of tag slugs (e.g. fraud,bin_list). Only disputes that have all of the specified tags attached are returned.
Order the list by defense deadline. asc returns the soonest-expiring disputes first, desc the furthest out; disputes with no deadline are returned last either way.
Exactly one sort[field] parameter may be given per request: a second one, a repeated one, a bare sort=field, or a direction other than asc or desc all return 400.
The last link resolves in either direction, and the page it returns is the one holding the disputes with no deadline.
asc, desc Order the list by the date the provider raised the dispute. This is the default ordering, descending, when no sort[field] parameter is given. Disputes with no such date are returned last either way.
The one-term limit and the last link behaviour apply here too, as described on sort[defensePeriodExpiresAt].
asc, desc Boolean indicating if the disputes summary should be included in the response.
Boolean indicating if the disputes payment should be included in the response.
Boolean indicating if the disputes instrument should be included in the response.
Boolean indicating if the representment plan status should be included in the response.
Boolean indicating if the assigned user email and username should be included in the response.
Response
Success.
Hide child attributes
Hide child attributes
Unique identifier of the Dispute in Payrails.
Date and time when the Dispute was created in Payrails.
Date and time when the Dispute was last updated in Payrails.
Unique identifier of the Provider that was used to process the Dispute.
Unique identifier of the merchant-specific Provider Configuration that was used to process the Dispute. This can include the set of credentials used, the merchant account, country, vertical, etc.
Unique identifier of the Dispute in the Provider.
Stage of the dispute.
Created, FraudReport, Retrieval, Chargeback, PreArbitration, Arbitration, Unknown Amount of the Dispute. May differ from amount of Payment.
List of reasons codes used when defending a Dispute.
Hide child attributes
Hide child attributes
Defense reason code provided by Provider.
Email of the user currently assigned to this dispute. Only present when includeUserEmail=true and a user is assigned.
Channel the customer used to raise the dispute.
Not every provider reports a channel, and the field is only populated on
disputes received after it was introduced. It is therefore absent on many
disputes, and absence says nothing about how the dispute was raised — do not
read a missing channel as the absence of an issuer chargeback.
Provider: the customer raised the dispute with the payment provider directly, without involving their bank.Issuer: the customer went to their card issuer or bank, so the dispute is a card chargeback.Alert: the dispute arrived as a pre-chargeback alert, and no chargeback has been raised yet.Unknown: the Provider reported a channel that Payrails does not recognize.
Provider, Issuer, Alert, Unknown Status of the chargeback.
Incoming, Executed, Reversed, SecondChargeback, IssuerReponseTimeframeExpired, ArbitrationReversed Status of the defense.
NotDefendable, Undefended, ReadyToSubmit, Submitted, Failed, UnderReview, Won, Lost, Accepted, Resolved, Unknown Date and time when the Dispute defense period expires.
Date and time when the Dispute was created in the Provider. Only present if informed by Provider.
Merchant-supplied reference for the payment that originated the Dispute (e.g. an order ID). Populated from the PSP notification for Adyen, PayPal, and Checkout.com disputes, or from the linked Payment for other providers. Omitted when not available.
Unique identifier in Payrails of the Payment that originated the Dispute. Only available if the Payment was created via Payrails. When handling Disputes related to Payments created outside Payrails, this field will be omitted.
Workspace ID that the Dispute belongs to.
Unique identifier of the workflow execution that manages this Dispute's lifecycle in Payrails. Present once the dispute-management workflow has been started for the Dispute; omitted otherwise.
Human-readable description of why the dispute was raised.
Provider-specific reason code for the dispute, when supplied by the Provider.
Card-scheme reason code for the dispute, when supplied by the Provider.
Free-text comments from the issuer or provider about the dispute, keyed by source. Populated for Adyen, Nuvei, PayPal, and Klarna disputes. Not provided for Checkout.com, Stripe, or Revolut. Omitted when not available.
Hide child attributes
Hide child attributes
Indicates whether liability has shifted away from the merchant, as determined by the Provider or by 3DS authentication data. When true, the issuer bears the chargeback liability. Null if not yet determined.
Hide child attributes
Hide child attributes
Unique identifier of the Payment in Payrails. Omitted for Disputes on Payments that were not created via Payrails.
Exact date and time when the Payment was created. Possibly differs slightly from the date in the PSP.
Unique identifier of the Provider that was used to process the Payment.
Name of the Provider that was used to process the Payment, e.g. Adyen, Checkout, Stripe.
Display name of the Provider that was used to process the Payment.
Unique identifier of the Payment in an external system, e.g. PSP.
Unique identifier of the merchant-specific Provider Configuration that was used to process the Payment. This can include the set of credentials used, the merchant account, country, vertical, etc.
Type of integration used to process the payment (in case the payment provider supports multiple).
Type of payment method used to process the payment.
Unique identifier of the Holder that is involved in the Payment.
Merchant-provided reference of the Holder involved in the Payment.
Merchant-provided reference for the Execution. Commonly, the identifier of the order on the Merchant's system.
Workspace ID that the Payment belongs to.
Optionally included details about the instrument used for the payment.
Hide child attributes
Hide child attributes
Id of the instrument.
Date and time when the Instrument was created in Payrails.
When the Instrument was last updated.
Unique identifier of the Holder in Payrails.
Represents the payment method type.
alexBankMa7fazty, applePay, audi2pay, bankAccount, card, 2c2p, vietQR, cibSmartWallet, easypaisa, etisalatCash, fawryMobileWallet, fawryPay, googlePay, jazzCash, nbePhoneCash, orangeCash, payPal, qnbEWallet, weCash, genericRedirect, alfa, konnect, eftPro, netBanking, upi, cashFreeWallet, paytmWallet, phonePe, iDeal, bancontact, klarnaPayLater, klarnaPayNow, klarnaPayOverTime, scalapay Status of the instrument.
created, deleted, enabled, disabled, transient Instrument name suitable for display.
Description of the instrument.
True if this instrument is set as default for the holder.
Merchant-provided reference for the instrument.
System-wide unique identifier of the Instrument. If two Holders have the same instrument stored, this value will be the same for both, but the instrument and token IDs will be different. Cannot be used for payments, should only be used for analytics and fraud prevention.
Represents the future usage to define the payment flows that the stored instrument will be used for.
Subscription, CardOnFile, UnscheduledCardOnFile Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID.
Mastercard Transaction Link Identifier (TLID) of the transaction series this instrument belongs to. Returned by the card network on the initial cardholder-initiated transaction and required on economically related merchant-initiated transactions, such as recurring payments and installments, when the series spans payment providers.
Type-specific information about the instrument.
- Card
- BankAccount
- PayPal
- GooglePay
- ApplePay
- DCB
- MBWay
Hide child attributes
Hide child attributes
Network of the instrument.
unspecified, visa, visadankort, mastercard, amex, diners, discover, unionpay, unionpayuzcard, maestro, maestrobancontact, hipercard, jcb, jcblankapay, argencard, aura, belkart, bpfuelcard, cabal, carnet, cirrus, chjonesfuelcard, uzcard, codensa, dankort, dinacard, duet, ebt, eftpos, elo, euroshellfuelcard, gecapital, bc, hrgstore, humo, lankapay, lukoilfuelcard, bancontact, meeza, newday, mir, ourocard, pagobancomat, paypak, paypal, phhfuelcard, prostir, rupay, sbercard, sodexo, starrewards, cencosud, naranja, troy, uatp, ukfuelcard, verve, voyager, vpay, wex, cmi, atm, bankcard, localbrand, loyalty, privatelabel, fuelcard, redfuelcard, redliquidfuelcard First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number).
6 - 8"416598"
Last digits of the Card number.
4Network of the instrument.
unspecified, visa, visadankort, mastercard, amex, diners, discover, unionpay, unionpayuzcard, maestro, maestrobancontact, hipercard, jcb, jcblankapay, argencard, aura, belkart, bpfuelcard, cabal, carnet, cirrus, chjonesfuelcard, uzcard, codensa, dankort, dinacard, duet, ebt, eftpos, elo, euroshellfuelcard, gecapital, bc, hrgstore, humo, lankapay, lukoilfuelcard, bancontact, meeza, newday, mir, ourocard, pagobancomat, paypak, paypal, phhfuelcard, prostir, rupay, sbercard, sodexo, starrewards, cencosud, naranja, troy, uatp, ukfuelcard, verve, voyager, vpay, wex, cmi, atm, bankcard, localbrand, loyalty, privatelabel, fuelcard, redfuelcard, redliquidfuelcard Information about an issuer by the given BIN (or IIN).
Hide child attributes
Hide child attributes
First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number).
6 - 8"416598"
Network of the instrument.
unspecified, visa, visadankort, mastercard, amex, diners, discover, unionpay, unionpayuzcard, maestro, maestrobancontact, hipercard, jcb, jcblankapay, argencard, aura, belkart, bpfuelcard, cabal, carnet, cirrus, chjonesfuelcard, uzcard, codensa, dankort, dinacard, duet, ebt, eftpos, elo, euroshellfuelcard, gecapital, bc, hrgstore, humo, lankapay, lukoilfuelcard, bancontact, meeza, newday, mir, ourocard, pagobancomat, paypak, paypal, phhfuelcard, prostir, rupay, sbercard, sodexo, starrewards, cencosud, naranja, troy, uatp, ukfuelcard, verve, voyager, vpay, wex, cmi, atm, bankcard, localbrand, loyalty, privatelabel, fuelcard, redfuelcard, redliquidfuelcard Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact.
bancontact, cartesbancaires, dankort, mada Name of the bank or institution that issued the card.
Country of the bank or institution that issued the card.
Hide child attributes
Hide child attributes
ISO 3166-1 alpha-2 country code.
^[A-Z]{2}$ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.
^[A-Z]{3}$The English name of the country. Returned by Payrails, but not interpreted in requests.
Segment of the card, e.g. gold, black, business.
Type of the card, e.g. credit, debit, prepaid, gift.
More information about the card type, e.g. personal, commercial.
Indicates whether the card credential represents a network token rather than a primary account number (PAN).
Indicates whether the card is enrolled in a Flexible Credential or Flex Card program supported by the network - e.g. Visa Flexible Credential, Mastercard FlexCard.
Billing Address of the instrument.
Hide child attributes
Hide child attributes
The name of the street of a postal address.
The number on the door, building, or room.
Additional addressing information, 2nd line of postal address.
The name of the suburb or area within a city.
The name of the city of a postal address.
The postal code.
The name of the state a postal address is in.
The country where the address is in.
Hide child attributes
Hide child attributes
ISO 3166-1 alpha-2 country code.
^[A-Z]{2}$ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.
^[A-Z]{3}$The English name of the country. Returned by Payrails, but not interpreted in requests.
Latitude of the address in the GPS coordinate system.
Longitude of the address in the GPS coordinate system.
The phone to contact in the address (can be different that the customer's).
Hide child attributes
Hide child attributes
The local number of the phone, such that countryCode + number can be dialed.
^[0-9]+$International prefix of the phone, if known separately.
^\+?[0-9]+$Name of the address, e.g. home, work.
Name of the person to whom the address belongs to.
Last name of the person to whom the address belongs to.
Email of the person to whom the address belongs to.
Expiry month of the Card.
2Expiry year of the Card.
4Name of the owner of the Card.
Payer-provided tax identification number (e.g. CPF in Brazil) collected on the instrument.
Metadata for the context of an execution. Includes Payrails-defined structures for most common fields used in workflows, but can also be extended by merchant or provider-specific fields. For more information, visit our Meta Fields guide. See Meta for every field.
List of evidences associated with this dispute.
Hide child attributes
Hide child attributes
Unique identifier of the Dispute in Payrails.
Date and time when the Dispute was created in Payrails.
Date and time when the Dispute was last updated in Payrails.
Display title of the evidence, usually the file name.
Status of the dispute evidence.
Active, Inactive, Unknown Provenance of the dispute evidence.
Merchant, Payrails, Unknown MIME type of the evidence content.
Size of the evidence content in bytes.
Inline JSON payload for inline-context evidences. Present only for evidences created from inlineContexts; omitted for file-backed evidence.
Workspace ID that the Dispute belongs to.
Labels assigned to this evidence for the dispute, used to categorise the document during representment.
Representment plan details for this dispute.
Hide child attributes
Hide child attributes
Unique identifier of the dispute in Payrails.
Date and time when the representment plan was created in Payrails.
Date and time when the representment plan was last updated in Payrails.
Status of the representment plan lifecycle.
GeneratingPlan, PlanReady, StoringEvidences, LabelingEvidences, EvidencesReady, GeneratingRepresentment, RepresentmentReady, Submitted Provider response identifier for representment plan generation.
Recommended action for the merchant (e.g. "defend" or "accept").
Explanation supporting the recommendation.
Defense reason codes with evidence options, grouped by provider reason code.
Hide child attributes
Hide child attributes
Adyen defense document type code.
Human-readable name for this defense document type.
Explanation of what this defense document type covers.
Whether this defense type is the recommended selection.
Evidence suggestions within this defense type.
Hide child attributes
Hide child attributes
Ordering position of this option within the defense type.
Suggested title for this evidence.
Suggested details to include for this evidence.
Whether this evidence is mandatory for the defense.
Machine-readable identifier for the evidence type.
Display metadata for the already-uploaded evidence file, present when evidenceId is set.
Hide child attributes
Hide child attributes
Human-readable file name or title of the uploaded evidence.
MIME type of the uploaded evidence file.
Size of the uploaded evidence file in bytes.
Ordered representment sections for this dispute.
Hide child attributes
Hide child attributes
Unique identifier of the representment section in Payrails.
Unique identifier of the dispute in Payrails.
Date and time when the representment section was created in Payrails.
Date and time when the representment section was last updated in Payrails.
Position of the section in the representment.
Indentation level of the section in the representment.
Type of representment section.
Text, Picture, Timeline Title of the text section when sectionType is Text.
Content of the text section when sectionType is Text.
Linked evidence identifier when sectionType is Picture.
Label for the picture section when sectionType is Picture.
Status of the representment plan lifecycle.
GeneratingPlan, PlanReady, StoringEvidences, LabelingEvidences, EvidencesReady, GeneratingRepresentment, RepresentmentReady, Submitted Tags attached to this dispute.
Hide child attributes
Hide child attributes
Unique identifier of the Tag.
Human-readable display name of the Tag.
URL-safe identifier derived from the Tag name.
Hex color code used to render the Tag (e.g. "#EF4444").
Tag type slug. Determines cardinality and grouping (e.g. "merchant_status", "default").
UUID of the tag_types row this tag belongs to.
Whether multiple tags of this type can be attached to the same dispute at once. single means at most one tag of this type per dispute; multi allows many.
single, multi Date and time when the Tag was created.
Date and time when the Tag was last updated.
Workspace the Tag belongs to. Null for org-level tags visible to all workspaces.
Optional description of the Tag.
Date and time when the Tag was soft-deleted. Null if active.
AI classifications for the evidences associated with this dispute. Only present when includeEvidenceClassifications=true.
Hide child attributes
Hide child attributes
Unique identifier of the evidence file that was classified.
Unique identifier of the dispute the evidence belongs to.
Classification status.
classifying, classified, failed AI-generated summary of the evidence file content.
AI-inferred document type (e.g. "receipt", "shipping_label").
AI-generated statement of what the evidence proves in the dispute context.
List of key facts extracted from the evidence.
Representment plan slots this evidence is suggested to fill, ordered by confidence.
Hide child attributes
Hide child attributes
Defense reason code of the plan slot this evidence matches.
Slug identifier of the matching plan evidence slot.
Position of the matching slot within the defense type.
AI-generated explanation for why this evidence matches the slot.
Identifier of the LLM provider response that produced this classification.
Date and time when the classification was created.
Date and time when the classification was last updated.