Skip to main content
Optimization Protection

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.
  • Each page returns a maximum of 5,000 records.
  • The API defaults to a pageSize of 1,000 records when you do not specify a pageSize.
Tip

When you do not specify a disputeTypes filter, the API returns only FIRST_CHARGEBACK records. To return all dispute types, set disputeTypes to ALL.

For pre-arbitration availability, refer to pre-arbitration availability.

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
platform-id

Use this ID to identify the platform sending the API request.

 N Header
entityIds

Any one of the following:

  • A list of unique processing entities
  • A list of unique company identifiers
 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.
  • PRE_ARBITRATION - Pre-arbitration occurs after you challenge a chargeback and the issuer rejects the representment. Each pre-arbitration case exists as a separate dispute record and references the related chargeback dispute.
  • ALL - Return disputes matching other filters, regardless of their type.
 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
paymentMethodList A list of payment method codes to filter disputes by card brand or payment type. N Body
initiatedStartDate You provide the date when the dispute case record is created in the Issuer system. This date is the start of the range in YYYY-MM-DD format. If you do not enter this date, disputeReceivedStartDate, or disputeReceivedEndDate, the range defaults to 90 days before the current date. N Body
initiatedEndDate You provide the date when the dispute case record is created in the Issuer system. This date is the end of the range in YYYY-MM-DD format. If you do not enter this date, disputeReceivedStartDate, or disputeReceivedEndDate, the range defaults to the current date. N Body
disputeReceivedStartDate You provide the date when the dispute case record is created in our system. This date is the start of the range in YYYY-MM-DD format. If you enter this date, the initiatedDate range does not default to another value. N Body
disputeReceivedEndDate You provide the date when the dispute case record is created in our system. This date is the end of the range in YYYY-MM-DD format. If you enter this date, the initiatedDate range does not default to another value. N Body
responseDueStartDate You provide the date when the dispute case answer is due. This date is the start of the range in YYYY-MM-DD format. If you enter this date, the initiatedDate range does not default to another value. N Body
responseDueEndDate You provide the date when the dispute case answer is due. This date is the end of the range in YYYY-MM-DD format. If you enter this date, the initiatedDate range does not default to another 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
issuerDocumentExpected

If this is set to true, expect an issuer document arrival in next few days depending on payment brand.

Allowed values:

  • true - The issuer provides chargeback documentation.
  • false - The issuer does not provide chargeback documentation.
issuerDocumentReceived

If this is set to true, an issuer document was received from the payment brand.

Allowed values:

  • true - We received the issuer documents. Check issuer document availability using the Get dispute documents endpoint.
  • false - We did not receive the issuer documents.
responseDueDate Due date for challenging the dispute, in YYYY-MM-DD format. For pre-arbitration, refer to the pre-arbitration response due date.
transactionId Use this ID to identify the transaction that is being disputed.
submitterPlatformId Use this ID to identify the facilitator of the transaction that is being disputed.
outcome

The outcome of a dispute.

  • For chargebacks, this indicates your financial outcome after the dispute is resolved.
  • For retrieval requests, this indicates whether the request was fulfilled.
  • For pre-arbitration, this indicates whether liability was accepted or contested.

Refer to the specific dispute type page for supported outcome values.

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": {
    "merchantIds": [
      "999150844140",
      "997241028650"
    ]
  },
  "disputeTypes": ["FIRST_CHARGEBACK"],
  "disputeStatuses": ["NEW"],
  "initiatedStartDate": "2025-01-01",
  "initiatedEndDate": "2025-09-09",
  "disputeReceivedStartDate": "2025-01-01",
  "disputeReceivedEndDate": "2025-09-09",
  "responseDueStartDate": "2025-01-01",
  "responseDueEndDate": "2025-09-09",
  "paymentMethodList": ["VI"],
  "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"
      },
      "issuerDocumentCode": 1,
      "issuerDocumentExpected": false,
      "issuerDocumentReceived": false,
      "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",
        "transactionId": "adaf45c4-03c4-49ca-881c-d300bcd0b050",
        "submitterPlatformId": "2567543546"
      },
      "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",
      "issuerDocumentCode": 1,
      "issuerDocumentExpected": false,
      "issuerDocumentReceived": false,
      "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",
        "transactionId": "adaf45c4-03c4-49ca-881c-d300bcd0b050",
        "submitterPlatformId": "2567582045"
      },
      "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": {
    "merchantIds": [
      999150844140,
      997241028650
    ]
  },
  "disputeTypes": ["FIRST_CHARGEBACK"],
  "disputeStatuses": ["NEW"],
  "initiatedStartDate": "2025-01-01",
  "initiatedEndDate": "2025-09-09",
  "disputeReceivedStartDate": "2025-01-01",
  "disputeReceivedEndDate": "2025-09-09",
  "responseDueStartDate": "2025-01-01",
  "responseDueEndDate": "2025-09-09",
  "paymentMethodList": ["VI"],
  "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",
      "issuerDocumentCode": 1,
      "issuerDocumentExpected": false,
      "issuerDocumentReceived": false,
      "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",
        "transactionId": "adaf45c4-03c4-49ca-881c-d300bcd0b050",
        "submitterPlatformId": "2567582045"
      },
      "merchantData": {
        "companyId": "999150844140",
        "merchantId": "999150844140",
        "companyName": "Shipping stratus3 LLC",
        "merchantName": "Shipping stratus3 LLC"
      }
    }
  ],
  "pagination": {
    "cursor": "eyJjaWQiOltdLCJtaWQiOlsiOTk5MTUwODQ0MTQwIiwiOTk3MjQxMDI4NjUwIl0sInBnIjozLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyJdLCJzdCI6WyJORVciXSwiaWRzIjoiMjAyNS0wMS0wMSIsImlkZSI6IjIwMjUtMDktMDkiLCJ0cGciOjMsInJzZHQiOiIyMDI1LTAxLTAxIiwicmVkdCI6IjIwMjUtMDktMDkifQ=="
  },
  "traceId": "c5643234-7be9-44ee-ab11-4612562811b8"
}

Get dispute documents

Pre-arbitration availability

Pre-arbitration response due date

Is this page helpful?