v1

latestOpenAPI 3.1.0Payrails GmbH2026-07-2614905.7 MB

Disputes

Defend a Dispute

Submit evidence to contest a dispute. Use this to send your defense materials directly to the payment provider.

post/dispute/disputes/{disputeId}/defend

Path parameters

disputeIdstring uuid required

Identifier of the resource in Payrails.

Headers

x-idempotency-keystring uuid required

Idempotency key to be used. Sending again the same key would return the same result without re-executing the update.

Response

Defense submitted and dispute updated.

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.

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

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