# Disputes Reporting

## Get Submitted Dispute Response

> Retrieve all merchant-submitted responses for a specific dispute case including comments and associated evidence file names.

```json
{"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"paths":{"/api/disputes/v2.0/merchantdisputes/{caseNumber}/responses":{"get":{"tags":["Disputes Reporting"],"summary":"Get Submitted Dispute Response","description":"Retrieve all merchant-submitted responses for a specific dispute case including comments and associated evidence file names.","parameters":[{"name":"caseNumber","in":"path","description":"The unique dispute case identification number. Example: CN12345678.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeResponseHistoryDto"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResults"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResults"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResults"}}}}}}}},"components":{"schemas":{"DisputeResponseHistoryDto":{"type":"object","properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/DisputeResponseDto"},"nullable":true}},"additionalProperties":false},"DisputeResponseDto":{"type":"object","properties":{"responseId":{"type":"string","description":"Unique identifier for the merchant's submitted dispute case response.","nullable":true},"caseNumber":{"type":"string","description":"Dispute case number associated with the merchant response.","nullable":true},"merchantNumber":{"type":"string","description":"The merchant's unique identification number.","nullable":true},"response":{"type":"string","description":"Text of the merchant's response or comment submitted for the dispute case.","nullable":true},"createDateTimeUtc":{"type":"string","description":"Date and time when the response was submitted in ISO 8601 UTC. Format: YYYY-MM-DDThh:mm:ss.sssZ.","format":"date-time"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentDto"},"description":"A list of evidence files attached to the merchant’s response.","nullable":true}},"additionalProperties":false,"description":"Contains a grouping of details related to a dispute case response."},"AttachmentDto":{"type":"object","properties":{"attachmentId":{"type":"integer","description":"Unique identifier for the evidence attachment.","format":"int32"},"fileName":{"type":"string","description":"Name of the evidence file provided by the merchant.","nullable":true}},"additionalProperties":false},"XErrorResults":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","nullable":true},"title":{"type":"string","description":"A short, human-readable summary of the problem.","nullable":true},"status":{"type":"integer","description":"The HTTP status code for this error.","format":"int32"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","nullable":true},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.","nullable":true},"otherProperties":{"type":"object","additionalProperties":{},"description":"Any additional error details returned by the API.","nullable":true}},"additionalProperties":false,"description":"Contains one or more error objects returned."}}}}
```

## Get Dispute Case History

> Retrieve the history of a specific dispute case number including all status updates.

```json
{"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"paths":{"/api/disputes/v2.0/merchantdisputes/{caseNumber}":{"get":{"tags":["Disputes Reporting"],"summary":"Get Dispute Case History","description":"Retrieve the history of a specific dispute case number including all status updates.","parameters":[{"name":"caseNumber","in":"path","description":"The unique dispute case identification number.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeCaseDetailDto"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResults"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResults"}}}}}}}},"components":{"schemas":{"DisputeCaseDetailDto":{"type":"object","properties":{"resellerHnk":{"type":"string","description":"The hierarchy node key (HNK) of the reseller associated with the merchant.","nullable":true},"resellerDba":{"type":"string","description":"The reseller's Doing Business As (DBA) name.","nullable":true},"parentHnk":{"type":"string","description":"The hierarchy node key (HNK) of the parent entity in the merchant hierarchy.","nullable":true},"parentDba":{"type":"string","description":"The parent entity's Doing Business As (DBA) name.","nullable":true},"mid":{"type":"string","description":"The merchant's unique identification number.","nullable":true},"midLegalName":{"type":"string","description":"The merchant's legal registered business name.","nullable":true},"midDba":{"type":"string","description":"The merchant's Doing Business As (DBA) name.","nullable":true},"familyId":{"type":"string","description":"The merchant's family or portfolio identifier used for internal grouping.","nullable":true},"caseNumber":{"type":"string","description":"The unique dispute case number assigned to the merchant dispute.","nullable":true},"caseType":{"type":"string","description":"Type of the dispute case involved. Possible values: Chargeback, Retrieval Request.","nullable":true},"reason":{"type":"string","description":"The reason description explaining why the dispute was initiated.","nullable":true},"cardNumber":{"type":"string","description":"The masked or last 4 digits of the card number used in the original transaction.","nullable":true},"cardType":{"type":"string","description":"The brand of the payment card used in the transaction.","nullable":true},"transactionType":{"type":"string","description":"The type of transaction involved in the dispute. Possible values: 05 - retail sale, 06 - credit, 07 - cash advance, 08 - quasi cash.","nullable":true},"originalTrxnFundsFlow":{"type":"string","description":"Indicates whether the original transaction was funded, reversed, or settled.","nullable":true},"originalReferenceNumber":{"type":"string","description":"The processor-assigned reference number for the original transaction associated with dispute.","nullable":true},"referenceNumber":{"type":"string","description":"Reference number associated with the chargeback or dispute case.","nullable":true},"transactionDate":{"type":"string","description":"Date when the original transaction occurred. Format: YYYY-MM-DD.","nullable":true},"transactionAmount":{"type":"number","description":"Amount of the original transaction.","format":"double"},"caseExpirationDate":{"type":"string","description":"Date when the dispute case expires if no action is taken.","nullable":true},"caseResolvedDate":{"type":"string","description":"Date when the dispute case was resolved. Format: YYYY-MM-DD.","nullable":true},"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/DisputeStatusHistoryDto"},"description":"List of status history entries showing the progression of the dispute case through various states.","nullable":true}},"additionalProperties":false},"DisputeStatusHistoryDto":{"type":"object","properties":{"status":{"type":"string","description":"The dispute status at the given point in time.","nullable":true},"disputeDate":{"type":"string","description":"Date when the dispute status was recorded. Format: YYYY-MM-DD.","nullable":true},"disputeAmount":{"type":"number","description":"The amount disputed at this status update.","format":"double","nullable":true},"merchantAmount":{"type":"number","description":"Amount claimed by the merchant for this status update.","format":"double","nullable":true},"respondByDate":{"type":"string","description":"The deadline for the merchant to submit a response. Format: YYYY-MM-DD.","nullable":true},"responseDate":{"type":"string","description":"Date when the merchant submitted a dispute response. Format: YYYY-MM-DD.","nullable":true}},"additionalProperties":false},"XErrorResults":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","nullable":true},"title":{"type":"string","description":"A short, human-readable summary of the problem.","nullable":true},"status":{"type":"integer","description":"The HTTP status code for this error.","format":"int32"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","nullable":true},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.","nullable":true},"otherProperties":{"type":"object","additionalProperties":{},"description":"Any additional error details returned by the API.","nullable":true}},"additionalProperties":false,"description":"Contains one or more error objects returned."}}}}
```

## Get Dispute Cases

> Retrieve a list of merchant dispute cases based on filtering and sorting capabilities.

```json
{"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"paths":{"/api/disputes/v2.0/merchantdisputes":{"get":{"tags":["Disputes Reporting"],"summary":"Get Dispute Cases","description":"Retrieve a list of merchant dispute cases based on filtering and sorting capabilities.","parameters":[{"name":"FromDate","in":"query","description":"Filters the results by the start date of the dispute cases. Default is the first day of the current month.","schema":{"type":"string","format":"date-time"}},{"name":"ToDate","in":"query","description":"Filters the results by the end date of the dispute cases. Default is today's date.","schema":{"type":"string","format":"date-time"}},{"name":"CardBrandName","in":"query","description":"Filters the results by the card brand name. For example: Visa, Mastercard, Amex, Discover. Defaults to all card brands. Comma-separated values are not supported.","schema":{"type":"string"}},{"name":"Status","in":"query","description":"Filters the results by the dispute status. For example: New Activity, Awaiting Response.","schema":{"type":"string"}},{"name":"PageNumber","in":"query","description":"Specifies the page number of results to return when pagination is applied. Default: 1.","schema":{"type":"integer","format":"int32"}},{"name":"PageSize","in":"query","description":"Specifies the number of results to return per page. Default: 25.","schema":{"type":"integer","format":"int32"}},{"name":"Sort.Field","in":"query","description":"Key-value pairs specifying fields sorted and sort direction (ASC or DESC).","schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SortingDirection"}}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeResponseViewModelPaginatedResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResults"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XErrorResponse"}}}}}}}},"components":{"schemas":{"SortingDirection":{"enum":["ASC","DESC"],"type":"string"},"DisputeResponseViewModelPaginatedResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DisputeResponseViewModel"},"description":"List of dispute case objects with details.","nullable":true},"page":{"$ref":"#/components/schemas/PaginationDto"}},"additionalProperties":false},"DisputeResponseViewModel":{"type":"object","properties":{"resellerHnk":{"type":"string","description":"The hierarchy node key (HNK) of the reseller associated with the merchant.","nullable":true},"resellerDba":{"type":"string","description":"The reseller's Doing Business As (DBA) name.","nullable":true},"parentHnk":{"type":"string","description":"The hierarchy node key (HNK) of the parent entity in the merchant hierarchy.","nullable":true},"parentDba":{"type":"string","description":"The parent entity's Doing Business As (DBA) name.","nullable":true},"mid":{"type":"string","description":"The merchant's unique identification number.","nullable":true},"midLegalName":{"type":"string","description":"The merchant's legal registered business name.","nullable":true},"midDba":{"type":"string","description":"The merchant's Doing Business As (DBA) name.","nullable":true},"familyId":{"type":"string","description":"The merchant's family or portfolio identifier used for internal grouping.","nullable":true},"caseNumber":{"type":"string","description":"The unique dispute case number assigned to the merchant dispute.","nullable":true},"caseType":{"type":"string","description":"Type of the dispute case involved. Possible values: Chargeback, Retrieval Request.","nullable":true},"reason":{"type":"string","description":"The reason description explaining why the dispute was initiated.","nullable":true},"status":{"type":"string","description":"Current status of the dispute case. Possible values: New Activity, Awaiting Response.","nullable":true},"cardNumber":{"type":"string","description":"The masked or last four digits of the card number associated with the transaction.","nullable":true},"cardType":{"type":"string","description":"The brand of the payment card used in the transaction.","nullable":true},"transactionType":{"type":"string","description":"The type of transaction involved in the dispute. Values: 05 - retail sale, 06- credit, 07- cash advance, 08 - quasi cash.","nullable":true},"originalTrxnFundsFlow":{"type":"string","description":"Indicates whether the original transaction was funded, reversed, or settled.","nullable":true},"originalReferenceNumber":{"type":"string","description":"The processor-assigned reference number for the original transaction associated with dispute.","nullable":true},"referenceNumber":{"type":"string","description":"Reference number associated with the chargeback or dispute case.","nullable":true},"transactionDate":{"type":"string","description":"Date when the original transaction occurred. Format: YYYY-MM-DD.","nullable":true},"transactionAmount":{"type":"number","description":"Amount of the original transaction.","format":"double"},"disputeDate":{"type":"string","description":"The date when the dispute was initiated. Format: YYYY-MM-DD.","nullable":true},"disputeAmount":{"type":"number","description":"The total amount under dispute.","format":"double"},"merchantAmount":{"type":"number","description":"The merchant's liability or adjustment amount related to the dispute.","format":"double"},"respondByDate":{"type":"string","description":"The last date by which the merchant must respond to the dispute. Format: YYYY-MM-DD.","nullable":true},"caseExpirationDate":{"type":"string","description":"Date when the dispute case is set to expire if no action is taken. Format: YYYY-MM-DD.","nullable":true},"responseDate":{"type":"string","description":"Date when the merchant submitted a response. Format: YYYY-MM-DD.","nullable":true},"caseResolvedDate":{"type":"string","description":"Date when the dispute case was resolved. Format: YYYY-MM-DD.","nullable":true}},"additionalProperties":false,"description":"Represents a merchant dispute response with comprehensive details about the dispute case and associated merchant hierarchy."},"PaginationDto":{"type":"object","properties":{"number":{"type":"integer","description":"Current page number in the paginated results.","format":"int32"},"size":{"type":"integer","description":"Number of records included per page.","format":"int32"},"sort":{"$ref":"#/components/schemas/SortDto"},"first":{"type":"boolean","description":"Indicates the current page is the first page in the result set."},"last":{"type":"boolean","description":"Indicates the current page is the last page in the result set."},"totalPages":{"type":"integer","description":"Total number of pages available based on the total elements and page size.","format":"int32"},"numberOfElements":{"type":"integer","description":"Number of records returned on the current page.","format":"int32"},"totalElements":{"type":"integer","description":"Total number of records available for the query across all pages.","format":"int32"}},"additionalProperties":false,"description":"Contains pagination details for the response."},"SortDto":{"type":"object","properties":{"field":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SortingDirection"},"description":"Key-value pairs specifying fields sorted and sort direction (ASC or DESC).","nullable":true}},"additionalProperties":false,"description":"Defines sorting criteria applied to the results."},"XErrorResponse":{"type":"object","properties":{"errorResults":{"type":"array","items":{"$ref":"#/components/schemas/XErrorResult"},"description":"Contains one or more error objects returned.","nullable":true}},"additionalProperties":false},"XErrorResult":{"type":"object","properties":{"errorMessage":{"type":"string","description":"Describes the reason for the error.","nullable":true},"resultCode":{"type":"integer","description":"Numeric code that identifies the type of error returned by the request.","format":"int32"},"timeStamp":{"type":"string","description":"Date and time when the error occurred, ISO 8601 format (UTC).","format":"date-time"}},"additionalProperties":false},"XErrorResults":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","nullable":true},"title":{"type":"string","description":"A short, human-readable summary of the problem.","nullable":true},"status":{"type":"integer","description":"The HTTP status code for this error.","format":"int32"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","nullable":true},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.","nullable":true},"otherProperties":{"type":"object","additionalProperties":{},"description":"Any additional error details returned by the API.","nullable":true}},"additionalProperties":false,"description":"Contains one or more error objects returned."}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xplorpay.com/api-reference/api/disputes/disputes-management/disputes-reporting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.