Get Dispute by ID

curl --request GET \
  --url https://api.staging.payrails.io/dispute/disputes/{disputeId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.staging.payrails.io/dispute/disputes/{disputeId}"

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/{disputeId}', 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/{disputeId}",
  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/{disputeId}"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/dispute/disputes/{disputeId}")

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

{
  "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"
}

GET

https://api.staging.payrails.io

dispute

disputes

{disputeId}

Get Dispute by ID

curl --request GET \
  --url https://api.staging.payrails.io/dispute/disputes/{disputeId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.staging.payrails.io/dispute/disputes/{disputeId}"

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/{disputeId}', 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/{disputeId}",
  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/{disputeId}"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.staging.payrails.io/dispute/disputes/{disputeId}")

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

{
  "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"
}

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

disputeId

string<uuid>

required

Identifier of the resource in Payrails.

Query Parameters

includePayment

boolean

default:false

Boolean indicating if the payment should be included in the response.

includeInstrument

boolean

default:false

Boolean indicating if the instrument should be included in the response.

includeHolderReference

boolean

default:false

Boolean indicating if the holder reference should be included in the response.

includeUserEmail

boolean

default:false

Boolean indicating if the assigned user email and username should be included in the response.

includeEvidences

boolean

default:false

Boolean indicating if evidences should be included in the response.

includeRepresentmentPlan

boolean

default:false

Boolean indicating if representment plan entities should be included in the response.

includeRepresentmentSections

boolean

default:false

Boolean indicating if representment sections should be included in the response.

includeEvidenceClassifications

boolean

default:false

Boolean indicating if AI evidence classifications should be included in the response.

Response

Dispute found, and all details are included.

string<uuid>

required

Unique identifier of the Dispute in Payrails.

createdAt

string<date-time>

required

Date and time when the Dispute was created in Payrails.

updatedAt

string<date-time>

required

Date and time when the Dispute was last updated in Payrails.

providerId

string<uuid>

required

Unique identifier of the Provider that was used to process the Dispute.

providerConfigId

string<uuid>

required

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.

providerReference

string

required

Unique identifier of the Dispute in the Provider.

stage

enum<string>

required

Stage of the dispute.

Available options:

Created,

FraudReport,

Retrieval,

Chargeback,

PreArbitration,

Arbitration,

Unknown

amount

object

Amount of the Dispute. May differ from amount of Payment.

Hide child attributes

amount.value

string

required

Decimal amount of the major currency unit. Can be any precision.

Pattern: [0-9]+(\.[0-9]+)?

Example:

"12.50"

amount.currency

string

required

ISO 3-letter currency code.

Pattern: ^[A-Z]{3}$

Example:

"EUR"

applicableDefenseReasons

object[]

List of reasons codes used when defending a Dispute.

Hide child attributes

applicableDefenseReasons.providerReasonCode

string

required

Defense reason code provided by Provider.

applicableDefenseReasons.evidenceTypes

object[]

Hide child attributes

applicableDefenseReasons.evidenceTypes.providerTypeCode

string

required

Code of the type of evidence provided by Provider.

assignedToUserId

string<uuid>

assignedToUserEmail

string

Email of the user currently assigned to this dispute. Only present when includeUserEmail=true and a user is assigned.

channel

enum<string>

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.

Available options:

Provider,

Issuer,

Alert,

Unknown

chargebackStatus

enum<string>

Status of the chargeback.

Available options:

Incoming,

Executed,

Reversed,

SecondChargeback,

IssuerReponseTimeframeExpired,

ArbitrationReversed

defenseStatus

enum<string>

Status of the defense.

Available options:

NotDefendable,

Undefended,

ReadyToSubmit,

Submitted,

Failed,

UnderReview,

Won,

Lost,

Accepted,

Resolved,

Unknown

defensePeriodExpiresAt

string<date-time>

Date and time when the Dispute defense period expires.

providerCreatedAt

string<date-time>

Date and time when the Dispute was created in the Provider. Only present if informed by Provider.

merchantReference

string

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.

paymentId

string<uuid>

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.

workspaceId

string<uuid>

Workspace ID that the Dispute belongs to.

executionId

string

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.

reason

string

Human-readable description of why the dispute was raised.

reasonCode

string

Provider-specific reason code for the dispute, when supplied by the Provider.

schemeReasonCode

string

Card-scheme reason code for the dispute, when supplied by the Provider.

issuerComments

object

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

issuerComments.{key}

string

liabilityShifted

boolean | null

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.

payment

object

Hide child attributes

payment.status

enum<string>

required

Current status of the Payment in Payrails. More information can be found here.

Available options:

Created,

Pending,

Unknown,

Failed,

Expired,

Preauthorized,

Authorized,

Canceled,

Captured,

Refunded

payment.id

string<uuid>

Unique identifier of the Payment in Payrails. Omitted for Disputes on Payments that were not created via Payrails.

payment.createdAt

string<date-time>

Exact date and time when the Payment was created. Possibly differs slightly from the date in the PSP.

payment.providerId

string<uuid>

Unique identifier of the Provider that was used to process the Payment.

payment.providerName

string

Name of the Provider that was used to process the Payment, e.g. Adyen, Checkout, Stripe.

payment.providerDisplayName

string

Display name of the Provider that was used to process the Payment.

payment.providerReference

string

Unique identifier of the Payment in an external system, e.g. PSP.

payment.providerConfigId

string<uuid>

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.

payment.providerIntegrationType

string

Type of integration used to process the payment (in case the payment provider supports multiple).

payment.paymentMethodType

string

Type of payment method used to process the payment.

payment.holderId

string<uuid>

Unique identifier of the Holder that is involved in the Payment.

payment.holderReference

string

Merchant-provided reference of the Holder involved in the Payment.

payment.amount

object

Amount of the Payment.

Hide child attributes

payment.amount.value

string

required

Decimal amount of the major currency unit. Can be any precision.

Pattern: [0-9]+(\.[0-9]+)?

Example:

"12.50"

payment.amount.currency

string

required

ISO 3-letter currency code.

Pattern: ^[A-Z]{3}$

Example:

"EUR"

payment.merchantReference

string

Merchant-provided reference for the Execution. Commonly, the identifier of the order on the Merchant's system.

payment.workspaceId

string<uuid>

Workspace ID that the Payment belongs to.

payment.instrument

object

Optionally included details about the instrument used for the payment.

Hide child attributes

payment.instrument.id

string<uuid>

required

Id of the instrument.

payment.instrument.createdAt

string<date-time>

required

Date and time when the Instrument was created in Payrails.

payment.instrument.updatedAt

string<date-time>

required

When the Instrument was last updated.

payment.instrument.holderId

string<uuid>

required

Unique identifier of the Holder in Payrails.

payment.instrument.paymentMethod

enum<string>

required

Represents the payment method type.

Available options:

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

payment.instrument.status

enum<string>

required

Status of the instrument.

Available options:

created,

deleted,

enabled,

disabled,

transient

payment.instrument.displayName

string

Instrument name suitable for display.

payment.instrument.description

string

Description of the instrument.

payment.instrument.default

boolean | null

True if this instrument is set as default for the holder.

payment.instrument.merchantReference

string

Merchant-provided reference for the instrument.

payment.instrument.fingerprint

string

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.

payment.instrument.futureUsage

enum<string>

Represents the future usage to define the payment flows that the stored instrument will be used for.

Available options:

Subscription,

CardOnFile,

UnscheduledCardOnFile

payment.instrument.networkTransactionReference

string

Identifier of the initial payment made with this instrument on the Networks, e.g. Mastercard Trace ID or Visa Transaction ID.

payment.instrument.transactionLinkId

string

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.

payment.instrument.data

Card · object

Type-specific information about the instrument.

Hide child attributes

payment.instrument.data.network

enum<string>

required

Network of the instrument.

Available options:

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

payment.instrument.data.bin

string

required

First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number).

Required string length: 6 - 8

Example:

"416598"

payment.instrument.data.suffix

string

required

Last digits of the Card number.

Required string length: 4

payment.instrument.data.preferredScheme

enum<string>

Network of the instrument.

Available options:

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

payment.instrument.data.binLookup

object

Information about an issuer by the given BIN (or IIN).

Hide child attributes

payment.instrument.data.binLookup.bin

string

required

First 6-8 digits of the Card number. Also known as IIN (Issuer Identification Number).

Required string length: 6 - 8

Example:

"416598"

payment.instrument.data.binLookup.network

enum<string>

Network of the instrument.

Available options:

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

payment.instrument.data.binLookup.localNetwork

enum<string>

Card local network that supports the card, e.g. CartesBancaires, Dankort, Mada, Bancontact.

Available options:

bancontact,

cartesbancaires,

dankort,

mada

payment.instrument.data.binLookup.issuer

string

Name of the bank or institution that issued the card.

payment.instrument.data.binLookup.issuerCountry

object

Country of the bank or institution that issued the card.

Hide child attributes

payment.instrument.data.binLookup.issuerCountry.code

string

required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$

payment.instrument.data.binLookup.issuerCountry.iso3

string

ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.

Pattern: ^[A-Z]{3}$

payment.instrument.data.binLookup.issuerCountry.name

string

The English name of the country. Returned by Payrails, but not interpreted in requests.

payment.instrument.data.binLookup.segment

string

Segment of the card, e.g. gold, black, business.

payment.instrument.data.binLookup.type

string

Type of the card, e.g. credit, debit, prepaid, gift.

payment.instrument.data.binLookup.typeDetails

string

More information about the card type, e.g. personal, commercial.

payment.instrument.data.binLookup.isNetworkToken

boolean

Indicates whether the card credential represents a network token rather than a primary account number (PAN).

payment.instrument.data.binLookup.isFlexCard

boolean

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.

payment.instrument.data.billingAddress

object

Billing Address of the instrument.

Hide child attributes

payment.instrument.data.billingAddress.street

string

The name of the street of a postal address.

payment.instrument.data.billingAddress.doorNumber

string

The number on the door, building, or room.

payment.instrument.data.billingAddress.complement

string

Additional addressing information, 2nd line of postal address.

payment.instrument.data.billingAddress.area

string

The name of the suburb or area within a city.

payment.instrument.data.billingAddress.city

string

The name of the city of a postal address.

payment.instrument.data.billingAddress.postalCode

string

The postal code.

payment.instrument.data.billingAddress.state

string

The name of the state a postal address is in.

payment.instrument.data.billingAddress.country

object

The country where the address is in.

Hide child attributes

payment.instrument.data.billingAddress.country.code

string

required

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$

payment.instrument.data.billingAddress.country.iso3

string

ISO 3-letter country code. Returned by Payrails, but not interpreted in requests.

Pattern: ^[A-Z]{3}$

payment.instrument.data.billingAddress.country.name

string

The English name of the country. Returned by Payrails, but not interpreted in requests.

payment.instrument.data.billingAddress.latitude

number<float>

Latitude of the address in the GPS coordinate system.

payment.instrument.data.billingAddress.longitude

number<float>

Longitude of the address in the GPS coordinate system.

payment.instrument.data.billingAddress.phone

object

The phone to contact in the address (can be different that the customer's).

Hide child attributes

payment.instrument.data.billingAddress.phone.number

string

required

The local number of the phone, such that countryCode + number can be dialed.

Pattern: ^[0-9]+$

payment.instrument.data.billingAddress.phone.countryCode

string

International prefix of the phone, if known separately.

Pattern: ^\+?[0-9]+$

payment.instrument.data.billingAddress.alias

string

Name of the address, e.g. home, work.

payment.instrument.data.billingAddress.name

string

Name of the person to whom the address belongs to.

payment.instrument.data.billingAddress.lastName

string

Last name of the person to whom the address belongs to.

payment.instrument.data.billingAddress.email

string

Email of the person to whom the address belongs to.

payment.instrument.data.expiryMonth

string

Expiry month of the Card.

Required string length: 2

payment.instrument.data.expiryYear

string

Expiry year of the Card.

Required string length: 4

payment.instrument.data.holderName

string

Name of the owner of the Card.

payment.instrument.data.taxId

string

Payer-provided tax identification number (e.g. CPF in Brazil) collected on the instrument.

payment.meta

object

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.

evidences

object[]

List of evidences associated with this dispute.

Hide child attributes

evidences.id

string<uuid>

required

Unique identifier of the Dispute in Payrails.

evidences.createdAt

string<date-time>

required

Date and time when the Dispute was created in Payrails.

evidences.updatedAt

string<date-time>

required

Date and time when the Dispute was last updated in Payrails.

evidences.displayTitle

string

Display title of the evidence, usually the file name.

evidences.status

enum<string>

Status of the dispute evidence.

Available options:

Active,

Inactive,

Unknown

evidences.provenance

enum<string>

Provenance of the dispute evidence.

Available options:

Merchant,

Payrails,

Unknown

evidences.contentType

string

MIME type of the evidence content.

evidences.contentLength

integer

Size of the evidence content in bytes.

evidences.payload

object

Inline JSON payload for inline-context evidences. Present only for evidences created from inlineContexts; omitted for file-backed evidence.

evidences.workspaceId

string<uuid>

Workspace ID that the Dispute belongs to.

evidences.labels

string[]

Labels assigned to this evidence for the dispute, used to categorise the document during representment.

representmentPlan

object

Representment plan details for this dispute.

Hide child attributes

representmentPlan.disputeId

string<uuid>

required

Unique identifier of the dispute in Payrails.

representmentPlan.createdAt

string<date-time>

required

Date and time when the representment plan was created in Payrails.

representmentPlan.updatedAt

string<date-time>

required

Date and time when the representment plan was last updated in Payrails.

representmentPlan.status

enum<string>

required

Status of the representment plan lifecycle.

Available options:

GeneratingPlan,

PlanReady,

StoringEvidences,

LabelingEvidences,

EvidencesReady,

GeneratingRepresentment,

RepresentmentReady,

Submitted

representmentPlan.providerResponseId

string

Provider response identifier for representment plan generation.

representmentPlan.recommendation

string

Recommended action for the merchant (e.g. "defend" or "accept").

representmentPlan.rationale

string

Explanation supporting the recommendation.

representmentPlan.defenseReasons

object[]

Defense reason codes with evidence options, grouped by provider reason code.

Hide child attributes

representmentPlan.defenseReasons.code

string

required

Adyen defense document type code.

representmentPlan.defenseReasons.title

string

required

Human-readable name for this defense document type.

representmentPlan.defenseReasons.description

string

required

Explanation of what this defense document type covers.

representmentPlan.defenseReasons.selected

boolean

required

Whether this defense type is the recommended selection.

representmentPlan.defenseReasons.options

object[]

required

Evidence suggestions within this defense type.

Hide child attributes

representmentPlan.defenseReasons.options.position

integer

required

Ordering position of this option within the defense type.

representmentPlan.defenseReasons.options.title

string

required

Suggested title for this evidence.

representmentPlan.defenseReasons.options.description

string

required

Suggested details to include for this evidence.

representmentPlan.defenseReasons.options.required

boolean

required

Whether this evidence is mandatory for the defense.

representmentPlan.defenseReasons.options.slug

string

Machine-readable identifier for the evidence type.

representmentPlan.defenseReasons.options.evidenceInfo

object

Display metadata for the already-uploaded evidence file, present when evidenceId is set.

Hide child attributes

representmentPlan.defenseReasons.options.evidenceInfo.displayTitle

string

Human-readable file name or title of the uploaded evidence.

representmentPlan.defenseReasons.options.evidenceInfo.contentType

string

MIME type of the uploaded evidence file.

representmentPlan.defenseReasons.options.evidenceInfo.contentLength

integer

Size of the uploaded evidence file in bytes.

representmentSections

object[]

Ordered representment sections for this dispute.

Hide child attributes

representmentSections.id

string<uuid>

required

Unique identifier of the representment section in Payrails.

representmentSections.disputeId

string<uuid>

required

Unique identifier of the dispute in Payrails.

representmentSections.createdAt

string<date-time>

required

Date and time when the representment section was created in Payrails.

representmentSections.updatedAt

string<date-time>

required

Date and time when the representment section was last updated in Payrails.

representmentSections.position

integer

required

Position of the section in the representment.

representmentSections.indent

integer

required

Indentation level of the section in the representment.

representmentSections.sectionType

enum<string>

required

Type of representment section.

Available options:

Text,

Picture,

Timeline

representmentSections.textSectionTitle

string

Title of the text section when sectionType is Text.

representmentSections.textSectionContent

string

Content of the text section when sectionType is Text.

representmentSections.pictureSectionEvidenceId

string<uuid>

Linked evidence identifier when sectionType is Picture.

representmentSections.pictureSectionLabel

string

Label for the picture section when sectionType is Picture.

representmentSections.pictureSectionEvidenceLinks

object

Links for downloading the picture section evidence file when sectionType is Picture.

Hide child attributes

representmentSections.pictureSectionEvidenceLinks.download

representmentPlanStatus

enum<string>

Status of the representment plan lifecycle.

Available options:

GeneratingPlan,

PlanReady,

StoringEvidences,

LabelingEvidences,

EvidencesReady,

GeneratingRepresentment,

RepresentmentReady,

Submitted

Payrails API Reference

Get started

Workflow

Payment

Provider

Merchant

Vault

Analytics

Reporting

Reconciliation

Dispute

Other

Get Dispute by ID

Authorizations

Path Parameters

Query Parameters

Response