Sign in

v1

latestOpenAPI 3.1.0Payrails GmbH2026-07-2614905.7 MB
Disputes

Get Dispute by ID

Retrieve a dispute by its ID. Use the include parameters to expand related objects such as payment details, evidence files, and representment sections in a single request.

get/dispute/disputes/{disputeId}

Path parameters

disputeIdstring uuid required

Identifier of the resource in Payrails.

Query parameters

includePaymentboolean

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

includeInstrumentboolean

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

includeHolderReferenceboolean

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

includeUserEmailboolean

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

includeEvidencesboolean

Boolean indicating if evidences should be included in the response.

includeRepresentmentPlanboolean

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

includeRepresentmentSectionsboolean

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

includeEvidenceClassificationsboolean

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

Response

Dispute found, and all details are included.

idstring uuid required

Unique identifier of the Dispute in Payrails.

createdAtstring date-time required

Date and time when the Dispute was created in Payrails.

updatedAtstring date-time required

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

assignedToUserIdstring uuid
assignedToUserEmailstring

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

chargebackStatus'Incoming' | 'Executed' | 'Reversed' | 'SecondChargeback' | 'IssuerReponseTimeframeExpired'

Status of the chargeback.

defenseStatus'NotDefendable' | 'Undefended' | 'ReadyToSubmit' | 'Submitted' | 'Failed' | 'UnderReview' | 'Won' | 'Lost' | 'Accepted' | 'Resolved' | 'Unknown'

Status of the defense.

defensePeriodExpiresAtstring date-time

Date and time when the Dispute defense period expires.

providerIdstring uuid required

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

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

providerReferencestring required

Unique identifier of the Dispute in the Provider.

providerCreatedAtstring date-time

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

merchantReferencestring

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.

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

workspaceIdstring uuid

Workspace ID that the Dispute belongs to.

reasonstring

Human-readable description of why the dispute was raised.

stage'Created' | 'FraudReport' | 'Retrieval' | 'Chargeback' | 'PreArbitration' | 'Arbitration' | 'Unknown' required

Stage of the dispute.

issuerCommentsobject
liabilityShiftedboolean nullable

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.

representmentPlanStatus'GeneratingPlan' | 'PlanReady' | 'StoringEvidences' | 'LabelingEvidences' | 'EvidencesReady' | 'GeneratingRepresentment' | 'RepresentmentReady' | 'Submitted'

Status of the representment plan lifecycle.

Example response

{
  "amount": {
    "value": "12.50",
    "currency": "EUR"
  },
  "payment": {
    "amount": {
      "value": "12.50",
      "currency": "EUR"
    },
    "instrument": {
      "data": {
        "bin": "416598",
        "binLookup": {
          "bin": "416598"
        }
      }
    },
    "meta": {
      "order": {
        "storeId": "store-123",
        "reference": "order_3573894940903",
        "placement": {
          "country": {
            "code": "DE"
          },
          "city": "Berlin"
        },
        "deliveryAddress": {
          "city": "Ankeborg",
          "country": {
            "code": "SE"
          },
          "doorNumber": "1",
          "street": "Stargatan",
          "postalCode": "12345",
          "name": "Peter",
          "lastName": "Parker",
          "email": "notbatman@gmail.com"
        },
        "billingAddress": {
          "city": "Ankeborg",
          "country": {
            "code": "SE"
          },
          "doorNumber": "1",
          "street": "Stargatan",
          "postalCode": "12345",
          "name": "Bruno",
          "lastName": "Diaz",
          "email": "iambatman@gmail.com"
        },
        "lines": [
          {
            "id": "123",
            "quantity": 1,
            "taxPercentage": {
              "value": "5"
            },
            "description": "Delicious Beer.",
            "name": "Beer 1",
            "total": {
              "value": "100",
              "currency": "SEK"
            },
            "links": {
              "productUrl": "https://www.amazingmerchant.com/products/1",
              "imageUrl": "https://www.amazingmerchant.com/products/1.jpeg"
            }
          }
        ]
      },
      "customer": {
        "reference": "1231905323475",
        "name": "FirstName",
        "lastName": "LastName",
        "email": "someone@email.com",
        "type": "VIP",
        "country": {
          "code": "SE"
        }
      },
      "clientContext": {
        "ipAddress": "217.110.239.132",
        "osType": "ios",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
        "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "language": "nl_NL",
        "colorDepth": 24,
        "screenHeight": 723,
        "screenWidth": 1536,
        "timeZoneOffset": 0,
        "javaEnabled": true,
        "javaScriptEnabled": true,
        "cookiesAccepted": true,
        "origin": "https://merchant.com/checkout",
        "host": "merchant.com"
      },
      "vendor": {
        "reference": "vendor-123",
        "name": "Cool Restaurant"
      },
      "risk": {
        "score": "80",
        "skipPaymentProviderRules": false,
        "force3DS": true,
        "threeDSMode": "Default",
        "allowNative3DS": true,
        "sessionId": "34567890123",
        "exemptionIndicator": "lowValue"
      },
      "subscription": {
        "chargeFrequency": "P2D",
        "expiration": "2000-09-01"
      },
      "tags": {
        "customKey": "customValue"
      }
    }
  }
}