v1

latestOpenAPI 3.1.0Payrails GmbH2026-07-2614905.7 MB

Disputes

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.

get/dispute/disputes

Query parameters

filter[id]string

Filter for a list of disputes by ID.

filter[providerId]string

Filter for a list of disputes by provider ID.

filter[providerConfigId]string

Filter for a list of disputes by provider config ID.

filter[providerReference]string

Filter for a list of disputes by provider reference.

filter[paymentId]string

Filter for a list of disputes by payment ID.

filter[paymentProviderReference]string

Filter for a list of disputes by payment provider reference.

filter[holderReference]string

Filter for a list of disputes by holder reference.

filter[stage]string

Filter for a list of disputes by stage.

filter[defenseStatus]string

Filter for a list of disputes by defense status.

filter[chargebackStatus]string

Filter for a list of disputes by chargeback status.

filter[assignedToUserEmail]string

Filter for a list of disputes by assigned to user email.

filter[defensePeriodExpiresAt]string date-time

Filter for a list of disputes by defense period expiration date.

filter[reason]string

Filter for a list of disputes by reason.

filter[reasonCode]string

Filter for a list of disputes by reason code.

filter[providerCreatedAt]string

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[merchantReference]string

Filter for a list of disputes by merchant reference.

filter[containsall][tags]string

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.

includeSummaryboolean

Boolean indicating if the disputes summary should be included in the response.

includePaymentboolean

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

includeInstrumentboolean

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

includeRepresentmentPlanStatusboolean

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

includeUserEmailboolean

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

Response

Success.

Example response

{
  "results": [
    {
      "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"
          }
        }
      }
    }
  ]
}