# Models ## The Attachment object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"Attachment":{"type":"object","properties":{"merchantNumber":{"type":"string","description":"The merchant's unique identification number associated with the attachment.","nullable":true},"attachmentId":{"type":"integer","description":"Unique identifier for the evidence attachment.","format":"int32"},"fileName":{"type":"string","description":"The name of the uploaded evidence file.","nullable":true},"filePath":{"type":"string","description":"The storage location or path of the uploaded file.","nullable":true},"uploadedDateTime":{"type":"string","description":"The date and time when the evidence file was uploaded. Format: YYYY-MM-DDThh:mm:ss.sssZ.","nullable":true}},"additionalProperties":false}}}} ``` ## The AttachmentDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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}}}} ``` ## The DisputeCaseDetailDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"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}}}} ``` ## The DisputeResponseDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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}}}} ``` ## The DisputeResponseHistoryDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"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}}}} ``` ## The DisputeResponseViewModel object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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."}}}} ``` ## The DisputeResponseViewModelPaginatedResponse object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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."},"SortingDirection":{"enum":["ASC","DESC"],"type":"string"}}}} ``` ## The DisputeStatusHistoryDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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}}}} ``` ## The PaginationDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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."},"SortingDirection":{"enum":["ASC","DESC"],"type":"string"}}}} ``` ## The SortDto object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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."},"SortingDirection":{"enum":["ASC","DESC"],"type":"string"}}}} ``` ## The SortingDirection object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"SortingDirection":{"enum":["ASC","DESC"],"type":"string"}}}} ``` ## The UploadEventResponse object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"UploadEventResponse":{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"},"description":"List of uploaded evidence file details.","nullable":true},"responseId":{"type":"integer","description":"Unique identifier for the submitted merchant response.","format":"int32"},"responseMessage":{"type":"string","description":"A message confirming the status of the submitted response.","nullable":true},"caseNumber":{"type":"string","description":"Unique dispute case identification number associated with the submitted response.","nullable":true},"exchangeId":{"type":"string","description":"Identifier used to track the exchange of information with the dispute processing system.","nullable":true},"correlationId":{"type":"string","description":"Unique identifier used for tracking the request across systems.","nullable":true},"parentId":{"type":"string","description":"Identifier that links the response to a parent transaction or message.","nullable":true},"parentSystemCode":{"type":"string","description":"System code for the upstream system that originated the request.","nullable":true},"merchantNumber":{"type":"string","description":"The merchant's unique identification number.","nullable":true}},"additionalProperties":false,"description":"Response containing upload event details for a submitted dispute case response."},"Attachment":{"type":"object","properties":{"merchantNumber":{"type":"string","description":"The merchant's unique identification number associated with the attachment.","nullable":true},"attachmentId":{"type":"integer","description":"Unique identifier for the evidence attachment.","format":"int32"},"fileName":{"type":"string","description":"The name of the uploaded evidence file.","nullable":true},"filePath":{"type":"string","description":"The storage location or path of the uploaded file.","nullable":true},"uploadedDateTime":{"type":"string","description":"The date and time when the evidence file was uploaded. Format: YYYY-MM-DDThh:mm:ss.sssZ.","nullable":true}},"additionalProperties":false}}}} ``` ## The XErrorResponse object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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}}}} ``` ## The XErrorResult object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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}}}} ``` ## The XErrorResults object ```json {"openapi":"3.0.1","info":{"title":"Dispute.API","version":"0.0.1"},"components":{"schemas":{"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/models.md?ask= ``` 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.