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 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," 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 J.P. Morgan. ACCEPTED - You accepted the liability. CHALLENGED_JPMC - Dispute challenged on your behalf by J.P. Morgan. UNDER_ISSUER_REVIEW - Dispute has been returned to the issuer for review. CHALLENGED_MERCHANT - Dispute challenged by you. CHALLENGE_DENIED - Case can not 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 the J.P. Morgan's 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 the J.P. Morgan's 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 will be returned as the output for the requested page in the paginated response.	N	Body
`cursor`	Indicates the starting point for 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 J.P. Morgan.
`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 next few days depending on payment brand. You can check the issuer document availability using our "documents" API endpoint. Allowed values: 0 - No Chargeback Documentation Provided by issuer. 1 - Supporting document will be provided by issuer. 2 - No Documents required by issuer. 3 - Documents are required by issuer. 4 - Non-receipt of required documents by issuer.
`responseDueDate`	Due date before which the you can challenge the dispute in YYYY-MM-DD format.
`outcome`	The outcome of a dispute. For chargebacks this will indicate the financial outcome for you after the dispute is solved. For retrieval requests, this will indicate whether the request have been fulfilled or not. Allowed Values: PENDING - Final decision/result pending. LOST - You lost dispute and a debit was done on your account for the total dispute amount. WON - You won 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 or RETRIEVAL_REQUEST disputeTypes with the statuses 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": [
           "447032"
        ]
    },
    "disputeTypes": ["FIRST_CHARGEBACK", "RETRIEVAL_REQUEST"],
    "disputeStatuses": ["NEW"],
    "initiatedStartDate": "",
    "initiatedEndDate": "",
    "disputeReceivedStartDate": "2024-04-01",
    "disputeReceivedEndDate": "2025-05-31",
    "pagination": {
        "pageSize": 2,
        "cursor": ""
    }
}

Response:

Json

{
  "requestId": "7064cf71-946b-49e8-bfa9-848675a41f1a",
  "disputes": [
    {
      "disputeType": "FIRST_CHARGEBACK",
      "disputeId": 256156730,
      "acquirerReferenceNumber": "74573513312100000852058",
      "disputeInitiatedDate": "2023-11-14",
      "disputeReceivedDate": "2024-08-16",
      "responseDueDate": "2023-12-08",
      "disputeValue": {
        "amount": 61.03,
        "currencyCode": "PLN"
      },
      "disputeReason": {
        "reasonCode": "12.3",
        "reason": "Incorrect Currency"
      },
      "disputeCategoryCode": "PROCESSING_ERROR",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": null,
      "outcome": "PENDING",
      "paymentMethod": {
        "paymentMethodCode": "VI",
        "paymentMethodName": "Visa",
        "maskedAccountNumber": "476122XXXXXX1118"
      },
      "issuerDocumentCode": null,
      "authorizationData": {
        "authorizationTimestamp": "2023-11-08T00:00:00Z",
        "authorizationReferenceNumber": null
      },
      "transactionData": {
        "merchantOrderNumber": "113 AUD_PLN 036_985x",
        "transactionTimestamp": "2023-11-08T00:00:00Z",
        "transactionAmount": 22.26,
        "transactionCurrency": "AUD"
      },
      "merchantData": {
        "companyId": "156182",
        "merchantId": "447032",
        "companyName": "PAPAGEORGE BONDING BARB",
        "merchantName": "Amazon.co.jp             "
      }
    },
    {
      "disputeType": "FIRST_CHARGEBACK",
      "disputeId": 256225142,
      "acquirerReferenceNumber": "52718584012100000182544",
      "disputeInitiatedDate": "2024-01-22",
      "disputeReceivedDate": "2024-08-14",
      "responseDueDate": "2024-03-01",
      "disputeValue": {
        "amount": 18506.48,
        "currencyCode": "PLN"
      },
      "disputeReason": {
        "reasonCode": "34",
        "reason": "Point of Interaction Error"
      },
      "disputeCategoryCode": "PROCESSING_ERROR",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": null,
      "outcome": "PENDING",
      "paymentMethod": {
        "paymentMethodCode": "MC",
        "paymentMethodName": "MasterXXXXXXcard",
        "maskedAccountNumber": "222241XXXXXX0017"
      },
      "issuerDocumentCode": null,
      "authorizationData": {
        "authorizationTimestamp": "2024-01-11T00:00:00Z",
        "authorizationReferenceNumber": null
      },
      "transactionData": {
        "merchantOrderNumber": "137 AUD_PLN 036_985s",
        "transactionTimestamp": "2024-01-12T00:00:00Z",
        "transactionAmount": 6750,
        "transactionCurrency": "AUD"
      },
      "merchantData": {
        "companyId": "156182",
        "merchantId": "447032",
        "companyName": "PAPAGEORGE BONDING BARB",
        "merchantName": "Amazon.co.jp             "
      }
    }
  ],
  "pagination": {
    "cursor": "eyJjaWQiOltdLCJtaWQiOlsiNDQ3MDMyIl0sInBnIjoyLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyIsIlJFVFJJRVZBTF9SRVFVRVNUIl0sInN0IjpbIk5FVyJdLCJ0cGciOjcsInJzZHQiOiIyMDI0LTA0LTAxIiwicmVkdCI6IjIwMjUtMDUtMzEifQ=="
  },
  "traceId": "1e410517-1859-44a0-86b7-56a2a01a7ee1"
}

Scenario: Building upon the previous scenario, in the current one, we can use the cursor returned from the response and get the remaining record(s).

Json

{
    "entityIds": {
        "companyIds": [],
        "merchantIds": [
           "447032"
        ]
    },
    "disputeTypes": ["FIRST_CHARGEBACK", "RETRIEVAL_REQUEST"],
    "disputeStatuses": ["NEW"],
    "initiatedStartDate": "",
    "initiatedEndDate": "",
    "disputeReceivedStartDate": "2024-04-01",
    "disputeReceivedEndDate": "2025-05-31",
    "pagination": {
        "pageSize": 2,
        "cursor": "eyJjaWQiOltdLCJtaWQiOlsiNDQ3MDMyIl0sInBnIjoyLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyIsIlJFVFJJRVZBTF9SRVFVRVNUIl0sInN0IjpbIk5FVyJdLCJ0cGciOjcsInJzZHQiOiIyMDI0LTA0LTAxIiwicmVkdCI6IjIwMjUtMDUtMzEifQ=="
    }
}

Response:

Json

{
  "requestId": "1918f871-2ab3-44aa-ac7a-20300b611dc6",
  "disputes": [
    {
      "disputeType": "FIRST_CHARGEBACK",
      "disputeId": 256252874,
      "acquirerReferenceNumber": "52718584012100000182544",
      "disputeInitiatedDate": "2024-01-22",
      "disputeReceivedDate": "2024-08-16",
      "responseDueDate": "2024-03-01",
      "disputeValue": {
        "amount": 18506.48,
        "currencyCode": "PLN"
      },
      "disputeReason": {
        "reasonCode": "34",
        "reason": "Point of Interaction Error"
      },
      "disputeCategoryCode": "PROCESSING_ERROR",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": null,
      "outcome": null,
      "paymentMethod": {
        "paymentMethodCode": "MC",
        "paymentMethodName": "MasterXXXXXXcard",
        "maskedAccountNumber": "222241XXXXXX0017"
      },
      "issuerDocumentCode": null,
      "authorizationData": {
        "authorizationTimestamp": "2024-01-11T00:00:00Z",
        "authorizationReferenceNumber": null
      },
      "transactionData": {
        "merchantOrderNumber": "137 AUD_PLN 036_985s",
        "transactionTimestamp": "2024-01-12T00:00:00Z",
        "transactionAmount": 6750,
        "transactionCurrency": "AUD"
      },
      "merchantData": {
        "companyId": "156182",
        "merchantId": "447032",
        "companyName": "PAPAGEORGE BONDING BARB",
        "merchantName": "Amazon.co.jp             "
      }
    },
    {
      "disputeType": "RETRIEVAL_REQUEST",
      "disputeId": 1972560997,
      "acquirerReferenceNumber": "79882722324669695020736",
      "disputeInitiatedDate": "2025-05-10",
      "disputeReceivedDate": "2025-05-15",
      "responseDueDate": "2025-05-11",
      "disputeValue": {
        "amount": 20,
        "currencyCode": "USD"
      },
      "disputeReason": {
        "reasonCode": "11.2",
        "reason": "Declined Authorization"
      },
      "disputeCategoryCode": "AUTHORIZATION",
      "disputeStatus": "NEW",
      "statusUpdateTimestamp": null,
      "outcome": null,
      "paymentMethod": {
        "paymentMethodCode": "VI",
        "paymentMethodName": "Visa",
        "maskedAccountNumber": "417292XXXXXX2496"
      },
      "issuerDocumentCode": null,
      "authorizationData": {
        "authorizationTimestamp": "2025-04-10T00:00:00Z",
        "authorizationReferenceNumber": null
      },
      "transactionData": {
        "merchantOrderNumber": "RATE VHFW VI",
        "transactionTimestamp": "2025-04-10T00:00:00Z",
        "transactionAmount": 20,
        "transactionCurrency": "USD"
      },
      "merchantData": {
        "companyId": "156182",
        "merchantId": "447032",
        "companyName": "PAPAGEORGE BONDING BARB",
        "merchantName": "Amazon.co.jp             "
      }
    }
  ],
  "pagination": {
    "cursor": "eyJjaWQiOltdLCJtaWQiOlsiNDQ3MDMyIl0sInBnIjozLCJsdCI6MiwiZHQiOlsiRklSU1RfQ0hBUkdFQkFDSyIsIlJFVFJJRVZBTF9SRVFVRVNUIl0sInN0IjpbIk5FVyJdLCJ0cGciOjcsInJzZHQiOiIyMDI0LTA0LTAxIiwicmVkdCI6IjIwMjUtMDUtMzEifQ=="
  },
  "traceId": "a4b454fd-4db8-4723-90bc-11ca6fb20033"
}