Skip to main content
Beta version

Dispute Management API is in the Beta phase.

Dispute Management

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
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.
 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. You can check the issuer document availability using our Get dispute documents endpoint.

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. You can check the issuer document availability using our Get dispute documents endpoint.

Allowed values:

  • true - We received the issuer documents.
  • false - We did not receive the issuer documents.
responseDueDate Due date before which you can challenge the dispute in YYYY-MM-DD format.
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 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",
  "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": {
    "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",
  "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