Retrieve disputes

You can retrieve a list of disputes, including chargebacks and retrieval requests, by sending a POST request to the /disputes endpoint.

To select a return of a more specific list of disputes in your retrieve disputes response, you can:

Use any of the following listed fields in your request as filters to restrict the list of disputes you retrieve.
Define the period you want to retrieve disputes for, using any of the date range fields. If no date range is specified, all disputes created within the last 90 days is returned.
Use pagination to limit the number of disputes returned. Indicate the number of records you want to retrieve per page. To navigate to next pages, send the subsequent requests using the same filter option as the original request. Also include the cursor field and value from the previous request response in your new request.

Note

Disputes are sorted by due date in ascending order.
There are a maximum of 5000 records, per page.

Important request fields

Important `POST` `/disputes` request fields
Request field name	Description	Required	Location
`request-id`	Unique request identifier provided by the requestor in the header.	Y	Header
`entityIds`	Any one of the following: A list of unique processing entities A list of unique company identifiers (Note: for future use)	Y	Body
`disputeTypes`	A list of labels representing the type or categories of disputes. Allowed values: `FIRST_CHARGEBACK` - This is the initial stage where the consumer disputes a transaction. The consumer contacts their bank or credit card issuer to report an issue, such as fraud, a billing error, or a product/service problem. `RETRIEVAL_REQUEST` - A retrieval request, also known as a "soft chargeback" or "request for information," that is a preliminary step in the dispute process where the consumer's bank requests additional information about a transaction from you. This request is typically initiated when a consumer questions a transaction on their statement but has not yet formally disputed the charge.	N	Body
`disputeStatuses`	A list of dispute status filters to apply when querying disputes. Allowed values: `ALL` - Return disputes matching other filters, regardless of their status. `NEW` - Dispute case received. `NEEDS_RESPONSE` - Dispute pending documents from you. `NEED_ADDITIONAL_INFORMATION` - More information requested by us. `ACCEPTED` - You accepted the liability. `CHALLENGED_JPMC` - Dispute challenged on your behalf by us. `UNDER_ISSUER_REVIEW` - Dispute has been returned to the issuer for review. `CHALLENGED_MERCHANT` - Dispute challenged by you. `CHALLENGE_DENIED` - Case cannot be challenged due to no representation rights per network rules. `CLOSED` - Dispute cycle complete. `EXPIRED` - Dispute has expired as due date has passed.	N	Body
`initiatedStartDate`	Indicates the date on which the dispute case record was created in the Issuer system. This serves as the start date of the range. If this date, along with `disputeReceivedStartDate` and `disputeReceivedEndDate`, is not provided, it defaults to 90 days prior to the current date.	N	Body
`initiatedEndDate`	Indicates the date on which the dispute case record was created in the Issuer system. This serves as the end date of the range. If this date, along with `disputeReceivedStartDate` and `disputeReceivedEndDate`, is not provided, it defaults to the current date.	N	Body
`disputeReceivedStartDate`	Indicates the date on which the dispute case record was created in our system. This serves as the start date of the range. If this date is provided, the `initiatedDate` range will not default to any other value.	N	Body
`disputeReceivedEndDate`	Indicates the date on which the dispute case record was created in our system. This serves as the end date of the range. If this date is provided, the `initiatedDate` range will not default to any other value.	N	Body
`pageSize`	Maximum number of records that is returned as the output for the requested page in the paginated response.	N	Body
`cursor`	Indicates the starting point for the next set of data on the paginated response. When you make a request to the API and receive a response with a next page cursor, you can use that cursor in a subsequent request to retrieve the next page of results.	N	Body

Important response fields

Important `POST` `/disputes` response fields
Response field name	Description
`disputeId`	A unique identifier provided by us.
`disputeCategoryCode`	The category of the dispute based on the reason code. Allowed values: `AUTHORIZATION` `CONSUMER_DISPUTE` `FRAUD` `PROCESSING_ERROR`
`issuerDocumentCode`	If this is set to 1, expect an issuer document arrival in the next few days, depending on the payment brand. You can check the issuer document availability using our documents API endpoint. Allowed values: 0 - No chargeback documentation provided by the issuer. 1 - Supporting document is provided by the issuer. 2 - No documents required by the issuer. 3 - Documents are required by the issuer. 4 - Non-receipt of required documents by the issuer.
`responseDueDate`	Due date before which you can challenge the dispute in YYYY-MM-DD format.
`outcome`	The outcome of a dispute. For chargebacks, this indicates the financial outcome for you after the dispute is solved. For retrieval requests, this indicates whether the request has been fulfilled or not. Allowed values: `PENDING` - Final decision/result pending. `LOST` - You lost the dispute and a debit was done on your account for the total dispute amount. `WON` - You won the dispute and your account has been credited back for the total dispute amount. `PARTIALLY_WON` - You won a partial amount of the disputed funds, and their account has been credited with this portion. `FULFILLED` - You have fulfilled the retrieval request. `NOT_FULFILLED` - You have not fulfilled the retrieval request.

HTTP method: POST

Endpoint: /disputes

Scenario: Obtain a list of disputes, for FIRST_CHARGEBACK disputeTypes with the disputeStatuses of NEW. Note that the pageSize is set to 2 and so, any records past this will be shown on a subsequent request using the cursor from the response.

Json

{
  "entityIds": {
    "companyIds": [],
    "merchantIds": [
      999150844140,
      997241028650
    ]
  },
  "disputeTypes": ["FIRST_CHARGEBACK"],
  "disputeStatuses": ["NEW"],
  "initiatedStartDate": "2025-01-01",
  "initiatedEndDate": "2025-09-09",
   "disputeReceivedStartDate": "2025-01-01",
  "disputeReceivedEndDate": "2025-09-09",
  "pagination": {
    "cursor": "",
    "pageSize": 2
  }
}

Response:

Json

{
  "requestId": "c0fde091-521c-41d1-a6b0-dfe8dadc52e3",
  "disputes": [
    {
      "disputeType": "FIRST_CHARGEBACK",
      "disputeId": 83015,
      "acquirerReferenceNumber": "24692165195100806126881",
      "disputeInitiatedDate": "2025-08-11",
      "disputeReceivedDate": "2025-08-11",
      "responseDueDate": "2025-08-29",
      "disputeValue": {
        "amount": 22,
        "currencyCode": "USD"
      },
      "disputeReason": {
        "reasonCode": "10.2",
        "reason": "EMV Liability Shift – Non-Counterfeit Fraud"
      },
      "disputeCategoryCode": "FRAUD",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": "2025-08-11T16:02:43Z",
      "outcome": "PENDING",
      "paymentMethod": {
        "paymentMethodCode": "VI",
        "paymentMethodName": "Visa",
        "maskedAccountNumber": "411234XXXXXX4113"
      },
      "authorizationData": {
        "authorizationTimestamp": "2025-07-14T00:00:00Z"
      },
      "transactionData": {
        "merchantOrderNumber": "Hh2iQThrIK6K8VGCp5oJGO",
        "transactionTimestamp": "2025-07-14T00:00:00Z",
        "transactionAmount": 22,
        "transactionCurrency": "USD"
      },
      "merchantData": {
        "companyId": "25887313631",
        "merchantId": "997241028650",
        "companyName": "Barker Mobility Equipments",
        "merchantName": "LA-US Safetech Fraud"
      }
    },
    {
      "disputeType": "FIRST_CHARGEBACK",
      "disputeId": 83020,
      "acquirerReferenceNumber": "74313305190100801793033",
      "disputeInitiatedDate": "2025-08-11",
      "disputeReceivedDate": "2025-08-11",
      "responseDueDate": "2025-08-29",
      "disputeValue": {
        "amount": 20,
        "currencyCode": "EUR"
      },
      "disputeReason": {
        "reasonCode": "10.2",
        "reason": "EMV Liability Shift – Non-Counterfeit Fraud"
      },
      "disputeCategoryCode": "FRAUD",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": "2025-08-11T16:02:43Z",
      "outcome": "PENDING",
      "paymentMethod": {
        "paymentMethodCode": "VI",
        "paymentMethodName": "Visa",
        "maskedAccountNumber": "400552XXXXXX0008"
      },
      "authorizationData": {
        "authorizationTimestamp": "2025-07-09T00:00:00Z"
      },
      "transactionData": {
        "merchantOrderNumber": "2jEAx26QkZ7DaKSCb4Lso8",
        "transactionTimestamp": "2025-07-09T00:00:00Z",
        "transactionAmount": 20,
        "transactionCurrency": "EUR"
      },
      "merchantData": {
        "companyId": "999150844140",
        "merchantId": "999150844140",
        "companyName": "Shipping stratus3 LLC",
        "merchantName": "Shipping stratus3 LLC"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJjaWQiOltdLCJtaWQiOlsiOTk5MTUwODQ0MTQwIiwiOTk3MjQxMDI4NjUwIl0sInBnIjoyLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyJdLCJzdCI6WyJORVciXSwiaWRzIjoiMjAyNS0wMS0wMSIsImlkZSI6IjIwMjUtMDktMDkiLCJ0cGciOjMsInJzZHQiOiIyMDI1LTAxLTAxIiwicmVkdCI6IjIwMjUtMDktMDkifQ=="
  },
  "traceId": "8ba1067b-629a-41a7-ba93-404348bb2d6e"
}

Scenario: Building upon the previous scenario, we can use the cursor returned from the response to retrieve the remaining record(s).

Json

{
  "entityIds": {
    "companyIds": [],
    "merchantIds": [
      999150844140,
      997241028650
    ]
  },
  "disputeTypes": ["FIRST_CHARGEBACK"],
  "disputeStatuses": ["NEW"],
  "initiatedStartDate": "2025-01-01",
  "initiatedEndDate": "2025-09-09",
   "disputeReceivedStartDate": "2025-01-01",
  "disputeReceivedEndDate": "2025-09-09",
  "pagination": {
    "cursor": "eyJjaWQiOltdLCJtaWQiOlsiOTk5MTUwODQ0MTQwIiwiOTk3MjQxMDI4NjUwIl0sInBnIjoyLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyJdLCJzdCI6WyJORVciXSwiaWRzIjoiMjAyNS0wMS0wMSIsImlkZSI6IjIwMjUtMDktMDkiLCJ0cGciOjMsInJzZHQiOiIyMDI1LTAxLTAxIiwicmVkdCI6IjIwMjUtMDktMDkifQ==",
    "pageSize": 2
  }
}

Response:

Json

{
  "requestId": "d3a738d4-6bd7-4f19-b4bf-f9bc349e5b23",
  "disputes": [
    {
      "disputeType": "FIRST_CHARGEBACK",
      "disputeId": 83021,
      "acquirerReferenceNumber": "74313305190100801793025",
      "disputeInitiatedDate": "2025-08-11",
      "disputeReceivedDate": "2025-08-11",
      "responseDueDate": "2025-09-04",
      "disputeValue": {
        "amount": 22,
        "currencyCode": "EUR"
      },
      "disputeReason": {
        "reasonCode": "13.6",
        "reason": "Credit Not Processed"
      },
      "disputeCategoryCode": "CONSUMER_DISPUTE",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": "2025-08-11T16:02:43Z",
      "paymentMethod": {
        "paymentMethodCode": "VI",
        "paymentMethodName": "Visa",
        "maskedAccountNumber": "400552XXXXXX0008"
      },
      "authorizationData": {
        "authorizationTimestamp": "2025-07-09T00:00:00Z"
      },
      "transactionData": {
        "merchantOrderNumber": "H1ymfZn3luhvKAQKqYt2cW",
        "transactionTimestamp": "2025-07-09T00:00:00Z",
        "transactionAmount": 22,
        "transactionCurrency": "EUR"
      },
      "merchantData": {
        "companyId": "999150844140",
        "merchantId": "999150844140",
        "companyName": "Shipping stratus3 LLC",
        "merchantName": "Shipping stratus3 LLC"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJjaWQiOltdLCJtaWQiOlsiOTk5MTUwODQ0MTQwIiwiOTk3MjQxMDI4NjUwIl0sInBnIjozLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyJdLCJzdCI6WyJORVciXSwiaWRzIjoiMjAyNS0wMS0wMSIsImlkZSI6IjIwMjUtMDktMDkiLCJ0cGciOjMsInJzZHQiOiIyMDI1LTAxLTAxIiwicmVkdCI6IjIwMjUtMDktMDkifQ=="
  },
  "traceId": "c5643234-7be9-44ee-ab11-4612562811b8"
}