# 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."}}}}
```